# 广告

当前SDK支持在游戏内创建并嵌入激励视频广告，接入之前需登录《QQ开放平台》 (opens new window)后台，进入“功能 > 广告接入”，新建“激励广告”并获取广告位ID。

# 激励视频广告

# 创建激励视频广告

调用 sdkInstance.createRewardedVideoAd(options) 接口创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可。

// 创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于QQ开放平台后台创建并生成
  adPlatform: "qq",
  adPosition: "",
  onLoad: function(response) {
    console.log(response.code); // 响应状态码，此处为0，表示加载成功
  },
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
    console.log(response.data.isCompleted); // 广告任务是否已完成，true 表示已完成，false 表示未完成
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
if (rewardedVideoAd) {
  // 手动加载一次激励视频广告
  rewardedVideoAd.load(callback?);

  // 展示激励视频广告
  rewardedVideoAd.show(options?, callback?);

  // 销毁激励视频广告实例
  rewardedVideoAd.destroy();
}

最低基础库版本要求

当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd(options) 接口将弹出升级提示，并返回 undefined，需要游戏客户端对返回值做兼容处理！

注意事项

默认情况下，游戏内创建的激励视频广告组件实例是一个全局单例，重复打开并观看广告时，无需多次创建，可直接使用首次创建的广告组件实例，调用实例的 show 方法展示即可！

创建激励视频广告实例的参数说明如下表所示：

选项	类型	必填	默认值	说明
adUnitId	string	是	--	广告位ID，请联系相关运营人员于QQ开放平台后台创建并生成
adPlatform	string	否	qq	广告平台
adPosition	string	否	--	广告展示位置，预留参数，有就填写
onLoad	function	否	--	激励视频广告加载成功时的回调函数
onClose	function	否	--	关闭激励视频广告时的回调函数，返回值中的 `isCompleted` 属性标记了用户是否已完成广告任务： `true` - 用户已完成广告任务，可以下发游戏奖励 `false` - 用户未完成广告任务，不可下发游戏奖励
onError	function	否	--	激励视频广告出错时的回调函数，返回值为当前错误信息

调用 sdkInstance.createRewardedVideoAd(options) 接口，将返回一个激励视频广告实例，默认是隐藏的，需要调用 rewardedVideoAd.show() 方法将其展示；具体实例方法如下表所示：

方法	类型	说明
load	function	用于手动加载一次激励视频广告
show	function	用于展示激励视频广告
destroy	function	用于销毁激励视频广告实例

# 加载激励视频广告

调用实例的 load 方法，可手动加载一次激励视频广告。一般情况下，创建广告实例，亦或关闭广告时，下一条待播广告将会默认自动加载一次，在需要播放时调用实例的 show 方法展示即可；如果出现加载失败而导致无法展示的情况，可尝试在适当时机利用 load 方法手动重新加载。

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
if (rewardedVideoAd) {
  // 广告实例的 show 方法用于展示广告
  rewardedVideoAd.show({ adPosition: "" }, function(showResponse) {
    // 响应状态码 showResponse.code 为 0 时表示展示成功，其他非 0 状态码均表示展示失败
    if (showResponse.code != 0) {
      // 展示失败，尝试手动重新加载
      rewardedVideoAd.load(function(loadResponse) {
        // 响应状态码 loadResponse.code 为 0 时表示加载成功，其他非 0 状态码均表示加载失败
        // 加载成功时，可再次调用 rewardedVideoAd.show({ adPosition: "" }) 重新展示
        // 加载失败时，可向用户弹出错误消息 loadResponse.message，亦可自定义失败提示
      });
    }
  });
}

实例 load 方法的参数说明如下表所示：

选项	类型	必填	默认值	说明
callback	function	否	--	调用 `load` 方法完成时的回调函数（加载成功或失败均会调用）；回调函数的返回值见下文说明

调用实例 load 方法完成时，其回调函数（加载成功或失败均会调用）的返回值说明如下表所示：

选项	类型	说明
code	number	响应状态码，为 `0` 时表示加载成功，其他非 `0` 状态码均表示加载失败
data	object / null	加载成功时返回相应广告数据（因QQAPI原因，此处可能为空），失败时返回 `null`
message	string	加载成功或失败时的相应描述信息

# 展示激励视频广告

调用实例的 show 方法，可展示激励视频广告，一般从屏幕下方推入。

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
if (rewardedVideoAd) {
  // 广告实例的 show 方法用于展示广告
  rewardedVideoAd.show({ adPosition: "" }, function(showResponse) {
    // 响应状态码 showResponse.code 为 0 时表示展示成功，其他非 0 状态码均表示展示失败
    // 展示失败时，可调用 rewardedVideoAd.load() 尝试手动重新加载
  });
}

实例 show 方法有两个参数：options、callback，均为非必填，具体说明如下表所示：

选项	类型	必填	默认值	说明
options	object	否	--	广告参数
options.adPosition	string	否	--	广告展示位置，此属性会在展示广告时覆盖 `createRewardedVideoAd` 接口中设置的属性，并以此进行数据上报
callback	function	否	--	调用 `show` 方法完成时的回调函数（展示成功或失败均会调用）；回调函数的返回值见下文说明

调用实例 show 方法完成时，其回调函数（展示成功或失败均会调用）的返回值说明如下表所示：

选项	类型	说明
code	number	响应状态码，为 `0` 时表示展示成功，其他非 `0` 状态码均表示展示失败
data	object / null	展示成功时返回相应广告数据（因QQAPI原因，此处可能为空），失败时返回 `null`
message	string	展示成功或失败时的相应描述信息

# 销毁激励视频广告

调用实例的 destroy 方法，可销毁激励视频广告实例。

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
if (rewardedVideoAd) {
  // 销毁激励视频广告实例
  rewardedVideoAd.destroy();
}

# 广告奖励发放

在创建激励视频广告实例时，需设置 onClose 事件回调函数，当关闭事件被触发时，通过事件回调函数的返回值判断是否应该下发相应的广告奖励：

// 创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于QQ开放平台后台创建并生成
  adPlatform: "qq",
  adPosition: "",
  onClose: function(response) {
    // 用户已完成广告任务，即广告正常播放结束
    if (response.data.isCompleted) {
      // 这里可以通知游戏服务器下发广告奖励
    }
    // 用户未完成广告任务，即广告播放中途退出
    else {
      // 这里可以提示用户尚未完成广告播放
    }
  }
});

如上例所示，onClose 事件回调函数的返回值中，response.data.isCompleted 属性取值如下所示：

true - 表示用户已完成广告任务，即广告正常播放结束，此时可以下发广告奖励
false - 表示用户未完成广告任务，即广告播放中途退出，此时不可下发广告奖励

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

/**
* 创建激励视频广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于QQ开放平台后台创建并生成
  adPlatform: "qq",
  adPosition: "",
  onLoad: function(response) {
    console.log(response.code); // 响应状态码，此处为0，表示加载成功
  },
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
    console.log(response.data.isCompleted); // 广告任务是否已完成，true 表示已完成，false 表示未完成
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

/**
* 用于加载广告
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
const loadRewardedVideoAd = function(options, times) {
  // 先判断 rewardedVideoAd 是否存在再使用
  // 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
  if (!rewardedVideoAd) {
    return sdkInstance.modal.message("暂不支持激励视频广告");
  }

  // 手动重新加载广告
  rewardedVideoAd.load(function(response) {
    // 响应状态码 response.code 为 0 时表示加载成功，可再次调用 show 方法进行展示
    if (response.code == 0) {
      showRewardedVideoAd(options, times);
    }
    // 其他非 0 状态码均表示加载失败，可向用户弹出错误消息 response.message，亦可自定义失败提示
    else {
      sdkInstance.modal.message(response.message);
    }
  });
};

/**
* 用于展示广告
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
const showRewardedVideoAd = function(options, times) {
  // 先判断 rewardedVideoAd 是否存在再使用
  // 因为当用户客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
  if (!rewardedVideoAd) {
    return sdkInstance.modal.message("暂不支持激励视频广告");
  }

  // 广告实例的 show 方法用于展示广告，默认是隐藏的
  rewardedVideoAd.show(options, function(response) {
    // 响应状态码 response.code 为 0 时表示展示成功
    if (response.code == 0) {
      console.log("广告展示成功");
    }
    // 其他非 0 状态码均表示展示失败，可尝试利用实例的 load 方法手动重新加载，并在加载成功后再次调用 show 方法进行展示
    else {
      // 重试次数大于0时进行重试
      if (times > 0) {
        loadRewardedVideoAd(options, times--);
      }
      // 反之弹出错误消息 response.message，亦可自定义失败提示
      else {
        sdkInstance.modal.message(response.message);
      }
    }
  });
};

/**
* 展示广告，例如点击游戏内按钮时调用此方法进行展示
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
showRewardedVideoAd({ adPosition: "" }, 3);

← 支付意见反馈（选接） →