From 9bb8d4a5480ece0993442653fc5169019f799846 Mon Sep 17 00:00:00 2001 From: handongxun Date: Mon, 17 Aug 2020 17:36:42 +0800 Subject: [PATCH] docs: ad --- docs/api/a-d/rewarded-video.md | 436 ++++++++++++++++----------------- 1 file changed, 213 insertions(+), 223 deletions(-) diff --git a/docs/api/a-d/rewarded-video.md b/docs/api/a-d/rewarded-video.md index 58b4128cd..c0130a862 100644 --- a/docs/api/a-d/rewarded-video.md +++ b/docs/api/a-d/rewarded-video.md @@ -64,212 +64,10 @@ ``` -### 显示/隐藏 -激励视频广告组件默认是隐藏的，在用户主动触发广告后，开发者需要调用 RewardedVideoAd.show() 进行显示。 - -``` -rewardedVideoAd.show() -``` - -只有在用户点击激励视频广告组件上的 关闭广告 按钮时，广告才会关闭。开发者不可控制激励视频广告组件的隐藏。 - -### 广告拉取成功与失败 - -激励视频广告组件是自动拉取广告并进行更新的。在组件创建后会拉取一次广告，用户点击 关闭广告 后会去拉取下一条广告。 - -如果拉取成功，通过 `RewardedVideoAd.onLoad()` 注册的回调函数会执行，`RewardedVideoAd.show()` 返回的 Promise 也会是一个 resolved Promise。两者的回调函数中都没有参数传递。 - -``` -rewardedVideoAd.onLoad(() => { - console.log('激励视频 广告加载成功') -}) - -rewardedVideoAd.show() -.then(() => console.log('激励视频 广告显示')) -``` - -如果拉取失败，通过 `RewardedVideoAd.onError()` 注册的回调函数会执行，回调函数的参数是一个包含错误信息的对象。常见异常错误参考文档 - -``` -rewardedVideoAd.onError(err => { - console.log(err) -}) -``` - -`RewardedVideoAd.show()` 返回的 Promise 也会是一个 rejected Promise。 - -``` -rewardedVideoAd.show() -.catch(err => console.log(err)) -``` - -### 拉取失败，重新拉取 - -如果组件的某次自动拉取失败，那么之后调用的 show() 将会被 reject。此时可以调用 `RewardedVideoAd.load()` 手动重新拉取广告。 - -``` -rewardedVideoAd.show() -.catch(() => { - rewardedVideoAd.load() - .then(() => rewardedVideoAd.show()) - .catch(err => { - console.log('激励视频 广告显示失败') - }) -}) -``` - -如果组件的自动拉取是成功的，那么调用 `load()` 方法会直接返回一个 resolved Promise，而不会去拉取广告。 - -``` -rewardedVideoAd.load() -.then(() => rewardedVideoAd.show()) -``` - -### 监听用户关闭广告 - -只有在用户点击激励视频广告组件上的 关闭广告 按钮时，广告才会关闭。这个事件可以通过 `RewardedVideoAd.onClose()` 监听。 - -`RewardedVideoAd.onClose()` 的回调函数会传入一个参数 res，res.isEnded 描述广告被关闭时的状态。 - - -|属性|类型|说明| -|:-:|:-:|:-:| -|isEnded|boolean|视频是否是在用户完整观看的情况下被关闭的，true 表示用户是在视频播放完以后关闭的视频，false 表示用户在视频播放过程中关闭了视频 - - -开发者需要根据 res.isEnded 判断是否视频是否播放结束、可以向用户下发奖励。 - -``` -rewardedVideoAd.onClose(res => { - // 用户点击了【关闭广告】按钮 - if (res && res.isEnded) { - // 正常播放结束 - } else { - // 播放中途退出 - } -}) -``` - - -### 服务器回调(App平台 HBuilderX 2.6.8，仅穿山甲支持) - -激励视频广告可以支持广告服务器到业务服务器的回调，用于业务系统判断是否提供奖励给观看广告的用户。配置服务器回调后，当用户成功看完广告时，广告服务器会访问配置的回调链接，通知用户完成观看激励视频。 - -相对来讲服务器回调将更加安全，可以依赖广告平台的反作弊机制来避免用户模拟观看广告完成的事件。 - -如何使用 -1. 申请激励视频广告位时开启服务器回调 -2. 创建激励视频广告时传入回调参数 - - -urlCallback示例 - -``` -rewardedVideoAd = uni.createRewardedVideoAd({ - adpid: '', - urlCallback: { - amount: '6', - name: 'RewardVideoAD1', - userId: 'testuser', - extra: 'testdata' - } -}); -``` - -### 服务器回调事件 -- HBuilderX 2.6.8+ - -``` -rewardedVideoAd.onVerify(e => { - // 广告商调用开发者服务器返回结果 - console.log(e.isValid); -}) -``` - -### 服务器回调数据说明 - -当最终用户观看激励视频广告完成后，广告服务器会以GET方式请求业务服务器的回调链接，并拼接以下参数回传： -`user_id=%s&trans_id=%s&reward_name=%s&reward_amount=%d&extra=%s&sign=%s` - -字段名称|说明|字段类型|备注| -:-|:-|:-|:-| -sign|签名|String|签名信息| -user_id|用户id|String |调用API传入的userId| -trans_id|交易id|String |广告平台生成的唯一交易ID| -reward_amount|奖励数量|String |广告后台配置或调用API传入的amount| -reward_name|奖励名称|String|广告后台配置或调用API传入的name| -extra|自定义数据，可以为空|String|透传给回调服务器的数据，调用API传入的extra| - -#### 签名信息 - -在uni-AD广告平台申请激励视频广告位通过后，如果开启服务器回调则会生成appSecurityKey。 -appSecurityKey用于签名校验服务器回调请求的合法性（请务必保管好），sign字段值生成规则为：sign=sha256(appSecurityKey,trans_id) -Python示例： - -``` -import hashlib - -if __name__ == "__main__": - trans_id = "6FEB23ACB0374985A2A52D282EDD5361u6643" - app_security_key = "7ca31ab0a59d69a42dd8abc7cf2d8fbd" - check_sign_raw = "%s:%s" % (app_security_key, trans_id) - sign = hashlib.sha256(check_sign_raw).hexdigest() -``` - -#### 回调请求返回数据约定 - -返回json数据，字段如下： - -字段名称|说明|字段类型|备注| -:-|:-|:-|:-| -isValid|校验结果|Blean|判定结果，是否发放奖励| - -示例 -``` -{ - "isValid": true -} -``` - -#### 获取广告商名称 -- HBuilderX 2.6.8+ - -``` -var rewardedVideoAd = uni.createRewardedVideoAd({ - adpid: '' -}); -var provider = rewardedVideoAd.getProvider(); -// csj gdt -``` - - -### app平台错误码 - -code|message| -:-|:-| --5001|广告位标识adpid为空，请传入有效的adpid --5002|无效的广告位标识adpid，请使用正确的adpid --5003|未开通广告，请在广告平台申请并确保已审核通过 --5004|无广告模块，打包时请配置要使用的广告模块 --5005|广告加载失败，请尝试重新加载 --5006|广告未加载完成无法播放，请加载完成后再调show播放 --5007|无法获取广告配置数据，请尝试重试 --5008|广告已过期，请重新加载数据 --5100|其他错误，聚合广告商内部错误 - - -**@error 详细错误码** - -- App端聚合的穿山甲(iOS)：[错误码](https://ad.oceanengine.com/union/media/union/download/detail?id=16&docId=5de8d574b1afac00129330d5&osType=ios) -- App端聚合的穿山甲(Android)：[错误码](https://ad.oceanengine.com/union/media/union/download/detail?id=4&docId=5de8d9b925b16b00113af0ed&osType=android) -- App端聚合的广点通(iOS)：[错误码](https://developers.adnet.qq.com/doc/ios/union/union_debug#%E9%94%99%E8%AF%AF%E7%A0%81) -- App端聚合的广点通(Android)：[错误码](https://developers.adnet.qq.com/doc/android/union/union_debug#sdk%20%E9%94%99%E8%AF%AF%E7%A0%81) - - -### 已封装好多页面调用示例(仅适用于app平台，注意看注释，根据自己业务需求修改) +### 完整调用示例 ```