# 广告
当前SDK支持在游戏内创建并嵌入商业化广告，接入之前请相关商务或运营人员开通小游戏流量主，入住阿里妈妈广告平台；入住成功后按照淘宝官方文档所述创建并设置相关广告位，并将生成的广告位ID提供给游戏客户端研发，否则无法进行联调测试。有关小游戏开通流量主、广告位创建及设置流程请阅读《广告商业化-小游戏接入指南》 (opens new window)文档说明，本文不做赘述；阿里妈妈的广告资质申请和技术API接入可同时进行。
# 激励广告
# 创建激励广告
调用 sdkInstance.createRewardedAd(options) 接口创建激励广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可。
// 创建激励广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedAd = sdkInstance.createRewardedAd({
adUnitId: "yourAdUnitId", // 请联系相关运营人员于淘宝开放平台后台创建并生成
adPlatform: "taobao",
adPosition: "",
onLoad: function(response) {
console.log(response.code); // 响应状态码，此处为0，表示加载成功
console.log(response.data); // 广告数据，其中包含广告图标、标题及描述信息
},
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); // 广告任务是否已完成，true 表示已完成，false 表示未完成
},
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，需要游戏客户端对返回值做兼容处理！
创建激励广告实例的参数说明如下表所示：
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| adUnitId | string | 是 | -- | 广告位ID，请联系相关运营人员于淘宝开放平台后台创建并生成 |
| adPlatform | string | 否 | taobao | 广告平台 |
| adPosition | string | 否 | -- | 广告展示位置，预留参数，有就填写 |
| onLoad | function | 否 | -- | 激励广告加载成功时的回调函数 |
| onClose | function | 否 | -- | 关闭激励广告时的回调函数 |
| 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 |
| data.icon | string | 广告图标 |
| data.title | string | 广告标题 |
| data.desc | string | 广告描述信息 |
| 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();
}
# 广告奖励发放
于淘宝开放平台后台创建及设置激励广告的广告位时，其广告细分类型一般分为以下三种类型：
- 浏览型广告：完成广告页面内的浏览任务，完成后可获得相应的任务奖励；
- 下单型广告：完成广告页面内的商品下单任务，完成后可获得相应的任务奖励；
- 浏览型+下单型广告：完成广告页面内的浏览任务，完成后可获得相应的任务奖励，浏览任务完成后，会呼起进阶的下单任务弹窗，用户完成进阶的下单任务后，可获得额外的任务奖励。
不同的广告细分类型，可采用不同的奖励发放方式，主要包括：游戏内回调、服务端回调（淘宝官方称为奇门回调）两种方式。
# 游戏内回调
奖励的发放方式为：游戏客户端接收到用户完成激励广告任务的回调（ onComplete 回调）时，自行通知服务端进行奖励的发放。
注意事项
此种奖励发放方式仅适用于「浏览型广告」！另外，若发放奖励为淘宝平台提供的平台权益（例如淘金币），请联系淘宝运营小二进行具体对接！
# 服务端回调（淘宝官方称为奇门回调）
奖励的发放方式为：当用户完成激励广告任务时，游戏服务端将接收到发放请求，由服务端完成用户奖励的发放，发放成功后，游戏客户端会收到 onComplete 回调。如果创建及设置广告位时使用此种奖励发放方式，则必须在淘宝开放平台后台进行道具配置管理：点击“新建奖励”，或者从“小游戏商业化 > 道具管理”栏目下点击“新建道具”进行道具新建。
注意事项
「下单型广告」和「浏览型+下单型广告」只能使用服务端回调（淘宝官方称为奇门回调）！游戏服务端需按照《服务端对接 - 广告奖励发放》文档要求，向相关运营人员提供广告奖励发放接口，并由运营人员配置至SDK开放平台后台，用于在玩家完成广告任务后通知游戏发放相应任务奖励！若有接口方面疑问，请咨询SDK服务端开发：邓泳辉！
# 示例代码
注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！
/**
* 创建激励广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const rewardedAd = sdkInstance.createRewardedAd({
adUnitId: "yourAdUnitId",
adPlatform: "taobao",
adPosition: "",
onLoad: function(response) {
console.log(response.code); // 响应状态码，此处为0，表示加载成功
console.log(response.data); // 广告数据，其中包含广告图标、标题及描述信息
},
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); // 广告任务是否已完成，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);
← 支付 打开客服会话（选接） →