【优量汇】试玩广告接入文档
【此文档针对广告主开发者接入】
一、关于试玩广告
1.1 介绍
试玩广告是一种新型的交互式广告，互动性强，相比于传统广告，它可以让用户在未下载APP的前提下抢先体验APP内容，提升用户点击下载意愿。
优量汇提供支持激励视频+试玩广告的形式，在激励视频播放完成后，自动弹出试玩广告页面供用户试玩，试玩完成后用户点击下载按钮可跳转至apple store，完成下载转化行为。
| 视频播放页 | 试玩播放页 |
|---|---|
二、整体流程★
请重点阅读整体流程:
2.1 试玩广告开发和SDK接入
按照 三、素材规范 和 四、试玩广告sdk接入规范，开发试玩广告和SDK接入。
2.2 试玩广告投放白名单申请
- 广告主提供广告主信息，包括账户id、账户信息、商品id等相关信息至优量汇侧，优量汇审核广告主资质；
- 广告主提交自测成果截图交由技术侧评估；
- 资质审核和技术评估通过后，运营为广告主开通试玩广告投放白名单。
2.3 试玩素材上传
按照 五、试玩广告素材上传 完成试玩素材上传。
2.4 试玩广告投放
按照 六、试玩广告投放 完成试玩素材上传。
三、素材规范
请广告主按照以下规范需求制作试玩素材
3.1 目录规范
素材打包为*.zip，根目录必须配置index.html、config.json。
/ //根目录
index.html // 试玩主文件
config.json // 试玩配置文件
其它目录(文件)
3.1.1 index.html说明
位于一级根目录中，静态资源引用使用相对路径，不能使用线上绝对路径访问(sdk除外)。
3.1.2 config.json说明
config.json：试玩广告播放方向等基本信息字段应存储于config.json文件中，位于一级目录中，配置如下：
{
"name": "试玩页名称", // 试玩名称
"version": "0.0.1", // 试玩版本
"config": {
"play_direction": 0, // 支持播放方向，默认为0：横竖版，1：竖版，2：横板
}
}
广告主需保障试玩素材针对横竖版的适配，及试玩广告针对不同机型的兼容性
3.2 包规范
- 包格式：zip；
- 包大小：不大于3M
3.3 文件规范
- 文件名称：素材所有文件名称仅支持大小写字母、数字、英文字符点、减号和下划线，不能使用中文命名；
- 素材中不允许使用mraid.js格式
3.4 安全规范
- 素材不允许通过外部网络加载动态素材
- 素材中不允许包含JS重定向
- 素材不允许发出HTTP、HTTPS请求（腾讯统计数据除外）
- 使用script标签请勿使用crossorigin设置
四、试玩广告sdk接入
unsdk.js 是提供给联盟广告主在试玩广告sdk，开发者接入unsdk后，根据文档要求实例化，当用户点击时，触发点击方法，即可完成点击操作。
4.1 开始接入SDK
在试玩广告页头部 head 中引入sdk地址：
<html>
<head>
<!-- 试玩广告sdk，请勿写死 http： -->
<script type="text/javascript" src="https://qzs.gdtimg.com/union/res/union_sdk/page/unjs/unsdk.js"></script>
</head>
<body>
<!--游戏canvas-->
<canvas />
</body>
</html>
4.2 SDK实例化
// 试玩广告实例化
window._gdtUnSdk = new window.GDTUnSdk({
type: 'playable', // String - 类型：试玩广告，必填
onSuccess: function(res) {
console.log(res) // 点击成功回调
},
onError: (res) => {
console.log(res) // 异常回调方法
}
})
// 需要点击转化的时候，由开发者主动调用点击上报方法
window._gdtUnSdk && window._gdtUnSdk.playAble.onClick()
- 参数说明
| 参数 | 方法介绍 | 类型 | 是否必填 | 备注 |
|---|---|---|---|---|
| type | 广告类型 | String | 是 | 'playable' - 试玩广告 |
| onSuccess | 触发点击api，点击成功回调 | Function | 否 | 建议填写，方便调试 |
| onError | 当实例化操作时，任何因素导致实例化失败，都会从这个回调返回 SDK错误码 |
Function | 否 | 建议填写，方便调试 |
4.3 完整接入代码示例
<html>
<head>
<script type="text/javascript" src="https://qzs.gdtimg.com/union/res/union_sdk/page/unjs/unsdk.js"></script>
</head>
<body>
<!--试玩广告 canvas-->
<canvas />
<script>
// 试玩广告实例化
window._gdtUnSdk = new window.GDTUnSdk({
type: 'playable', // String - 类型：试玩广告，必填
onSuccess: function(res) {
console.log(res) // 点击成功回调
},
onError: (res) => {
console.log(res) // 异常回调方法
}
})
// 需要点击转化的时候，由开发者主动调用点击上报方法
window._gdtUnSdk && window._gdtUnSdk.playAble.onClick()
</script>
</body>
</html>
4.4 试玩素材自测
试玩广告SDK接入完成后，可参考《试玩广告素材自测指南》 完成自测
五、试玩广告素材上传
5.1 访问素材中心
- 访问投放端 --> 工具箱 --> 素材中心
5.2 上传素材
- 进入素材中心，点击“上传试玩素材”
- 上传试玩素材zip包
六、试玩广告投放
6.1 创建激励视频+试玩广告
审核通过后，在投放端新建推广计划-新建广告，在广告版位上选择“优量汇”，在优量汇广告展示场景中选择“激励视频”
广告创建完成后，创建视频广告素材，并在试玩广告一栏，选择之前在素材中心上传的试玩广告素材。
完成广告创建，开始投放
七、附件
SDK错误码
| 错误码 | 错误内容 | 改进措施 |
|---|---|---|
| 1002 | 实例化参数 type 错误, 设置type: "playable" | 实例type值为:"playable" |
素材上传错误信息
| 错误内容 | 问题定位 |
|---|---|
| zip file contains unsafe file，xxx | 提示非法文件具体路径，需广告主按照目录规范自查 |
| zip file does not contain index.html in root path | 根路径下没有包含index.html，广告主按照素材规范自查 |
| zip file does not contain index.html in root path | 根路径没有包含config.json，广告主按照素材规范自查 |
| upload zip file failed | 系统错误，请稍后重试，可联系技术支持 |
| index.html has unsafe function | index.html页面包含了document.write方法 |
| file or directory name include non utf-8 encoding chinese characters | 压缩包内文件不能使用中文命名的目录或者文件 |