1. 描述

本版块将那些支持播放视频获取奖励的小游戏平台，统一封装成一个可调起视频的接口showVideo，调用后会播放视频；并根据实际播放结果触发相对应的回调。调用后可能出现无法拉取视频的情况，可根据下文提到的查看研发自测栏确认问题并解决。

广告组件已支持以下视频事件，游戏内只需要传入name属性即可：

事件名	是否支持	上报时机
video_click	是	点击视频点时，播放视频前。
video_play	是	视频开始播放时（或视频关闭时）
video_success	是	视频播放结束时
video_fail	是	视频中途关闭时

以下是对传入的参数对象内的属性详细说明：

• name 视频点名称，必须传入；由于涉及事件统计，建议由需求方直接提供该参数值，该参数用于上面表格中的统计事件

• show 视频播放时执行并返回当前播放的广告的id

• success 视频播放结束并关闭后执行，返回刚刚播放的视频的id，可在本回调内发放奖励

• fail 视频中途（倒计时结束前）关闭时执行

• error 视频拉取错误时触发

• eventProperties 自定义视频事件属性对象集合，只有在需求方明确说明需要该参数时才传入

2. 接入说明

请在需要展示视频时直接调用展示视频的接口并传入参数即可。

2.1 开发建议

游戏内有背景音乐时，建议在调用showVideo接口时暂停背景音，在success、fail、error回调中恢复背景音，如果不手动关闭，可能出现关闭视频后背景音效停止的问题。

2.2 video_show事件（选接）

视频事件中，有一个名为video_show的事件，统计视频点按钮的展示次数，由于与游戏内的UI逻辑相关，若市场方提出需要对该事件进行统计时，请在游戏内视频点按钮每次展示时调用以下方法埋点：

// videoName未视频点名称，与调用GameHelper.AdsFunc.showVideo内的name属性一致
GameHelper.GameStatistics.ShowVideo(videoName);

2.3 研发自测

正常情况下，视频成功创建的log如下：

如果调用接口后未展示视频，在调试包(debugMode=tue)的情况下，可在控制台依次查看以下内容

• 是否配置了延迟展示时间，log内容中最后的数字表示延迟时间；

  视频日延迟时间：每次调用播放接口时检测当日在线时长是否满足延迟时间，不满足则不展示；

  视频延迟时间：累积总在线时长（重启游戏后继续计时），满足该时长才会展示；

  

• 在保证视频广告id正确的情况下，无法出现视频时一般会触发视频错误监听，可在控制台log中检索"视频播放错误"关键字，根据错误码做对应处理，错误码见文档末尾；

• 若未检测到上面的错误监听信息，则表示广告调用创建接口后无响应；目前在广告ID填错时会出现该情况，可找发布方和id配置方确认广告id是否正确。

  

接口索引

视频有两个模块:

新模块名: GameHelper.AdsVideoManager

旧模块名：GameHelper.AdsFunc.showVideo

新接入视频功能建议使用新模块方法GameHelper.AdsVideoManager

GameHelper.AdsVideoManager

播放视频

GameHelper.AdsVideoManager.showVideo(String videoName, Object opts)

小游戏和app通用的播放视频接口

调用后会播放一个视频

参数

参数	类型	默认值	是否必填	说明
videoName	string	""	是	视频点名称，用于视频埋点统计
opt	videoOpts	/	是	初始化参数对象

videoOpts

参数	类型	默认值	是否必填	说明
statExt	object	/	否	统计相关的扩展属性参数小游戏端只能插入VIDEO_EVENT_PROPERTY中的属性（见文档末尾）
success	(videoName, extra) => {}	/	是	视频播放结束时执行，可在该回调内执行奖励逻辑
fail	(videoName,extra) => {}	/	否	视频播放中途（倒计时结束前）关闭时执行的回调
error	(videoName, err, extra) => {}	/	否	视频获取失败时执行的回调

GameHelper.AdsVideoManager.showVideo("testVideo", {
    statExt: {
        video_param: "videoParamTest",
        video_param1: "videoParamTest1",
        video_param2: "videoParamTest2",
        video_type: 20,
        video_type1: 0,
    },
    success: (videoName, extra?) => {
        console.log("新视频接口视频播放成功", videoName, extra);
    },
    fail: (videoName, extra?) => {
        console.log("新视频接口的中途关闭", videoName, extra);
    },
    error: (videoName, err?, extra?) => {
        console.log("新视频错误", videoName, err, extra);
    }
})

设置视频点免费

GameHelper.AdsVideoManager.free

将该属性赋值为true，后续调用GameHelper.AdsVideoManager.showVideo时都将直接执行success回调

兼容app端接口

以下属性和接口为了方便业务层使用同一个项目发app和小游戏，且app和小游戏并非同一套SDK；

所以小游戏SDK对以下接口仅增加属性或者函数名，确保游戏侧调用时不报错，但接口调用无效

GameHelper.AdsVideoManager.statValid

GameHelper.AdsVideoManager.addVideoNode()

GameHelper.AdsVideoManager.setVideoStatus()

GameHelper.AdsFunc.showVideo

播放视频

GameHelper.AdsFunc.showVideo(opt)

调用后正常情况下会播放一个视频，若未拉到视频广告会弹出一个拉取失败的提示；

参数	类型	默认值	是否必填	说明
opt	videoParams	/	是	初始化参数对象

videoParams

参数	类型	默认值	是否必填	说明
name	string	/	是	视频点名称，用于video_click、video_show等视频事件的属性上报
show	(res) => {}	/	否	视频播放时执行，会返回当前使用的广告ID
success	(res) => {}	/	是	视频播放结束时执行，可在该回调内执行奖励逻辑，会返回当前使用的广告ID
fail	function	/	否	视频播放中途（倒计时结束前）关闭时执行的回调
error	function	/	否	视频获取失败时执行的回调
eventProperties	VIDEO_EVENT_PROPERTY	/	否	自定义视频事件属性对象

GameHelper.AdsFunc.showVideo({
    name: "tool1",
    show: (res) => {
        console.log("视频开始播放,当前播放的视频id是", res.id);
    },
    success: (res) => {
        console.log("视频播放回调res：", res.id);
    },
    fail: () => {
        GameHelper.CCComFun.showToast({ title: "视频中途关闭" });
    },
    error: () => {
        console.log("视频获取失败");
    },
    eventProperties: {
        video_param: "videoParamTest",
        video_param1: "videoParamTest1",
        video_param2: "videoParamTest2",
        video_type: 20,
        video_type1: 0,
    }
});

VIDEO_EVENT_PROPERTY

注意只能传入以下声明的属性名称，传入其他未声明的属性名称无效；如传入了video_param5，该参数将丢弃，只上报已声明的属性

参数	类型	是否必填	说明
video_param	string	否	自定义的字符串类型的属性参数
video_param1
video_param2
video_param3
video_param4
video_type	number	否	自定义的数字类型的属性参数
video_type1
video_type2
video_type3
video_type4