# 腾讯优量汇广告使用指南
## 一、使用前须知
### 1、账号准备
多端应用已支持 App 的「开屏广告」和「激励广告」，而该能力是基于[腾讯优量汇-流量管理](https://ad.qq.com/dev/help.html)服务实现，开发者需前往腾讯优量汇官方[注册账号](https://ad.qq.com/dev/help_detail.html?cid=819&pid=1871)，并创建媒体和广告位。为方便开发者更好地理解整体逻辑，需认真阅读本章节的内容：
- 首先，前往腾讯优量汇控制台[注册开发者账号](https://ad.qq.com/dev/help_detail.html?cid=819&pid=1871)，并完成企业资质认证
- 前往「流量合作」创建媒体和广告位，获得相应的媒体 id 和广告位 id，具体使用上请查看下文的说明
### 2、关于 SDK 版本要求
- 开屏广告：iOS SDK 需使用版本号 ≥ 1.0.20；Android SDK 需使用版本号 ≥ 1.0.14
- 激励广告：iOS SDK 需使用版本号 ≥ 1.3.21；Android SDK 需使用版本号 ≥ 1.3.17
- 视频流广告和 banner 广告：iOS SDK 需使用版本号 ≥ 1.6.10；Android SDK 需使用版本号 ≥ 1.6.7
即，开发者需升级 SDK 版本至上述要求的版本方可使用 GDT SDK 相关能力
### 3、注意事项
- GDT SDK 会对 bundleId 进行校验，如果 bundleId 与创建媒体时填的不一致，则无法成功展示广告。
- 即，为正常拉取广告，开发者构建 IPA 时需选择「证书签名」，不可选择「临时签名」；
- 以及，该多端应用已经绑定移动应用，即构建 IPA 时显示的 bundleId 不是官方分配的测试版 bundleId
- 此外，新创建的广告位，30 分钟后才能开始拉取到广告，开发者需知悉
- 最后，腾讯优量汇账号需完成企业资质认证，创建的 appid、placementId 才能正常拉取到广告，也需开发者知悉
- 补充说明：开启了腾讯优量汇广告的 App 暂不支持上架 Google Play，即如果你的 App 需上架 Google Play，不要勾选「GDT SDK」
### 4、关于合规指南
根据监管部门要求，使用 SDK 时必须在《隐私政策》中告知终端用户 SDK 使用用途，并且在终端用户未同意《隐私政策》前不得初始化任何 SDK。请确保你开发或运营的应用有符合监管要求的《隐私政策》文本。同时请你务必明确告知终端用户你的应用使用了广告服务。并需遵守下方相关的协议
- [腾讯广告优量汇开发者协议](https://public.gdtimg.com/adnet-web/static/agreement/contract20230626.html)
- [腾讯广告优量汇开发者违规处罚规则](https://e.qq.com/dev/help_detail.html?cid=632&pid=2267)
- [开发者个人信息保护合规指引](https://e.qq.com/dev/help_detail.html?cid=2004&pid=5795)
- [优量汇SDK个人信息保护规则](https://e.qq.com/dev/help_detail.html?cid=2005&pid=5983)
- [数据保护协议](https://e.qq.com/dev/help_detail.html?cid=2052&pid=6170)
## 二、开屏广告操作指南
本章节的操作指南仅包含开发者工具上的操作，更多关于腾讯优量汇控制台操作可前往其官网进行查看相关指引
- [腾讯优量汇 - 账号注册](https://ad.qq.com/dev/help_detail.html?cid=819&pid=1871)
- [腾讯优量汇 - 新建媒体](https://ad.qq.com/dev/help_detail.html?cid=652&pid=1930)
- [腾讯优量汇 - 新建广告位](https://ad.qq.com/dev/help_detail.html?cid=654&pid=1938)，新建广告位的时候选择「开屏广告」
开发者工具的操作指引如下：
- 在 `project.miniapp.json` 中配置启用「GDT SDK」，并填入对应的媒体 id 和广告 id
- 从 iOS >= 1.2.9 开始，开发者可在设置开屏广告后，设置是否默认展示开屏广告。SDK 也提供 [wx.miniapp.setEnableAdSplash](/framework/dev/jsapi/miniapp/setEnableAdSplash.md) 让开发者实现自定义控制。
## 三、激励广告操作指南
本章节的操作指南仅包含开发者工具上的操作，更多关于腾讯优量汇控制台操作可前往其官网进行查看相关指引
- [腾讯优量汇 - 账号注册](https://ad.qq.com/dev/help_detail.html?cid=819&pid=1871)
- [腾讯优量汇 - 新建媒体](https://ad.qq.com/dev/help_detail.html?cid=652&pid=1930)
- [腾讯优量汇 - 新建广告位](https://ad.qq.com/dev/help_detail.html?cid=654&pid=1938)，新建广告位的时候选择「激励视频广告」
开发者工具的操作指引如下：
- 在 `project.miniapp.json` 中配置启用「GDT SDK」，并填入对应的媒体 id
- 然后调用 `wx.miniapp.createRewardedVideoAd` 创建激励视频广告组件，其中 adUnitId 即为广告位 id
### 3.1 wx.miniapp.createRewardedVideoAd
创建激励视频广告组件，即调用该方法创建的激励视频广告是一个单例。调用示例可参考[wx.createRewardedVideoAd](/miniprogram/dev/framework/open-ability/ad/rewarded-video-ad.md)
#### 参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
| ---- | ---- | ------ | -------- | ---- |
| adUnitId | string | | 是 | 广告位 id |
| multiton | boolean | | 否 | 是否启用多例模式，只支持 false |
#### 返回值
参考小程序的[RewardedVideoAd](/miniprogram/dev/api/ad/RewardedVideoAd.md)
- [加载激励视频广告](/miniprogram/dev/api/ad/RewardedVideoAd.load.md)
- [显示激励视频广告](/miniprogram/dev/api/ad/RewardedVideoAd.show.md)
- [销毁激励视频广告实例](/miniprogram/dev/api/ad/RewardedVideoAd.destroy.md)
- [监听激励视频广告加载事件](/miniprogram/dev/api/ad/RewardedVideoAd.onLoad.md)
- [移除激励视频广告加载事件的监听函数](/miniprogram/dev/api/ad/RewardedVideoAd.offLoad.md)
- [监听激励视频错误事件](/miniprogram/dev/api/ad/RewardedVideoAd.onError.md)
- [移除激励视频错误事件的监听函数](/miniprogram/dev/api/ad/RewardedVideoAd.offError.md)
- [监听用户点击`关闭广告`按钮的事件](/miniprogram/dev/api/ad/RewardedVideoAd.onClose.md)
- [移除用户点击`关闭广告`按钮的事件的监听函数](/miniprogram/dev/api/ad/RewardedVideoAd.offClose.md)
## 四、视频流广告和 banner 广告操作指南
- 由于 App 的广告与小程序的广告组件使用有区别，因此在对接视频流广告和 banner 广告之前需详细阅读腾讯优量汇官方文档
- 视频流广告对应这个文档：[https://e.qq.com/dev/help_detail.html?cid=3435&pid=10093](https://e.qq.com/dev/help_detail.html?cid=3435&pid=10093)
- banner 广告对应这个文档：[https://e.qq.com/dev/help_detail.html?cid=3434&pid=10084](https://e.qq.com/dev/help_detail.html?cid=3434&pid=10084)
- 填写正确的 `placement-id` 即可，调用示例如下：
```html
--- 这下面是视频流(express)广告 ----
-------
```
```html
--- 这下面是 banner 广告 ----
-------
```
- 注意事项：在创建广告位时，广告样式需选择「优量汇渲染」，场景点选择「其他位置的广告」
