# 广告

当前SDK支持在游戏内创建并嵌入商业化广告，接入之前请相关商务或运营人员开通小游戏流量主，入驻支付宝商家平台；入驻成功后按照支付宝官方文档所述创建并设置相关广告位，并将生成的广告位ID提供给游戏客户端研发，否则无法进行联调测试。有关小游戏开通流量主、广告位创建及设置流程请阅读《小游戏激励广告接入流程》 (opens new window)文档说明，本文不做赘述；商家平台的广告资质申请和技术API接入可同时进行。

# 激励广告

# 创建激励广告

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

// 创建激励广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedAd = sdkInstance.createRewardedAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于支付宝商家平台后台创建并生成
  adPlatform: "alipay",
  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 表示未完成
  },
  onComplete: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
    console.log(response.data.isCompleted); // 广告任务是否已完成，onComplete 回调函数中恒为 true，表示已完成，否则不会触发 onComplete 回调函数
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

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

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

  // 销毁激励广告实例
  rewardedAd.destroy();
}

最低基础库版本要求

当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedAd(options) 接口将返回 undefined，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示），需要游戏客户端对返回值做兼容处理！

注意事项

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

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

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

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

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

# 加载激励广告

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

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

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

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

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

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

# 展示激励广告

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

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

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

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

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

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

# 销毁激励广告

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

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

# 广告奖励发放

于支付宝商家平台后台创建及设置激励广告的广告位时，其广告玩法类型一般分为以下两种类型：

浏览型广告（默认）：完成广告页面内的浏览任务（视频观看或商品信息流浏览），完成后可获得相应的任务奖励；
浏览型+下单型广告（激励下单玩法）：完成广告页面内的浏览任务，完成后可获得相应的小额浏览奖励；浏览任务完成后，用户可选择完成进阶的商品下单任务，完成后可获得额外的大额下单奖励。有关激励下单玩法的更多内容请阅读《激励广告下单玩法接入流程》 (opens new window)文档。

不同的广告玩法类型，可采用不同的奖励发放方式，主要包括：游戏内回调、服务端回调两种方式。

# 游戏内回调

奖励的发放方式为：在创建激励广告实例时，设置 onClose 事件回调函数，当用户关闭广告时，通过回调函数返回值中的 response.data.isCompleted 属性判断用户是否已完成广告任务，并据此决定是否通知服务端下发相应的广告奖励。

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

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

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

此外，SDK还提供了 onComplete 回调函数，仅在用户完成广告任务时触发（即 response.data.isCompleted 为 true 时），可作为补充使用。

注意事项

此种奖励发放方式仅适用于「浏览型广告」！若广告位启用了「激励下单玩法」，浏览奖励仍通过此方式发放，但下单奖励必须使用下述「服务端回调」的方式进行发放！

# 服务端回调

奖励的发放方式为：当用户在激励广告中完成商品下单任务时，支付宝服务端将通过商家配置的回调URL通知SDK服务端，SDK服务端将中转通知至游戏侧，并由游戏服务端完成用户下单奖励的发放。此外，若用户下单获取奖励后发生退单，游戏服务端也将接收到退单通知，商家可据此决定是否收回已发放的奖励。

如果创建及设置广告位时启用了「激励下单」玩法，则必须在支付宝商家平台后台的"广告位管理 > 编辑"中打开"激励下单"选项，并配置下单任务完成通知URL（必填）和下单任务退单通知URL（选填）。注意，支付宝商家平台后台配置的回调URL应使用SDK服务端提供的回调URL。

注意事项

「浏览型+下单型广告（激励下单玩法）」的下单奖励只能使用服务端回调！游戏服务端需按照《服务端对接 - 广告奖励发放》文档要求，向相关运营人员提供广告奖励发放接口，并由运营人员配置至SDK开放平台后台，用于在玩家完成广告下单任务后通知游戏发放相应任务奖励！若有接口方面疑问，请咨询SDK服务端开发：邓泳辉！

# 示例代码

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

/**
* 创建激励广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const rewardedAd = sdkInstance.createRewardedAd({
  adUnitId: "yourAdUnitId",
  adPlatform: "alipay",
  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 loadRewardedAd = function(options, times) {
  // 先判断 rewardedAd 是否存在再使用
  // 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedAd 接口将返回 undefined
  if (!rewardedAd) {
    return sdkInstance.modal.message("暂不支持激励广告");
  }

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

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

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

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

← 支付添加到首页 →