Android iOS Unity JS API Media API 常见问题

H5 SDK 接入文档

类别 文档版本 更新时间 文档备注
文档更新 1.0.4 2020-05-27 1. 提升反作弊和广告质量,H5 SDK取消imei、idfa上报api,只针对腾讯手Q、微信、手Q浏览器、X5内核返回广告数据
文档更新 1.0.3 2019-07-23 1. 新增原生自定义模板样式使用广告说明
文档更新 1.0.2 2019-03-20 1. 新增H5 SDK激励视频接入说明
2. banner2.0\插屏2.0接入说明
文档版本 1.0.1 2018-11-18 1. 优化自定义模板广告接入说明
文档版本 1.0.0 2017-09-10 1. 文档创建

1 广告类型和环境建议

1.1 广告类型说明

以下是优量汇H5广告支持的场景类型,你可以根据你自身的产品流量和用户场景,选择适合的广告类型接入:

广告类型 使用场景 接入难度
banner广告 游戏、视频、阅读等固定区域 简单
插屏广告 主要提供弹框广告 简单
模板广告 提供左右图文、上下图文、纯图、三小图等样式,具体访问原生模板广告接入
可与网站列表、表格、内容等形态融入
简单
激励视频广告 小游戏、阅读、播放等激励场景 中等

2.1 浏览器环境

优量汇H5 SDK支持所有的浏览器环境,包括各流量主App的WebView、Chrome、Safari、QQ浏览器、手Q和微信等环境。但对于广告转化效果而言,我们有以下策略保证这些环境的流量,可能会有较高收益:

  1. 腾讯系APP:手Q、QQ浏览器、微信等腾讯系APP使用的Webview环境;
  2. 腾讯联盟SDK:使用腾讯联盟SDK(Android、iOS)Webview环境,具体见iOS和Android接入文档;
  3. QQ登录:广告播放所在页面使用了QQ登录;

对于第三方浏览器环境(包括百度、UC等)使用优量汇H5 SDK,可能会涉及浏览器自身的屏蔽策略。

2 H5广告位创建流程

2.1 接入步骤

  1. 首先在腾讯广告·优量汇官网 https://e.qq.com/dev 进行帐号注册;
  2. 在优量汇后台 新建H5媒体
  3. 媒体审核通过后,即可新建广告位,即可按照 3.H5 SDK接入流程 接入广告;
  4. 部署H5 SDK代码,并测试;
  5. 发布网页;
  6. 查看收益并优化。

2.2 H5广告接入步骤详解

2.2.1 新建H5媒体

新建H5媒体路径: 流量合作 => 我的媒体 => 新建媒体 => 选择应用平台和商店 => H5平台

新建H5媒体时,按流程需要 网站域名校验 和提供 网站的ICP备案。请按平台提示进行网站域名校验(绑定),目前我们提供的验证方式有两种:

注意:关于广告域名校验规则如下:

  1. 只有www.qq.com 等价于 qq.com
  2. 广告位不能在不同的三级域名混用,例如:adnet.qq.come.qq.com不等价,广告位不能混用。
  3. 广告媒体注册二级域名,广告位可以在二级域名子域名下。例如在媒体注册:qq.com,广告位可以在adnet.qq.come.qq.com 域名下使用,反之不可使用。
  4. 优量汇所有的域名必须通过ICP备案,关于ICP备案详见:https://cloud.tencent.com/document/product/243/19024

2.2.2 新建广告位

有两种方式可以新建广告位:

2.2.3 选择广告场景

点击 新建广告位 后,可以创建banner、插屏、和原生广告位

2.2.4 获取JS示例代码

我的广告位 列表中,点击对应操作栏的H5广告,即可通过 获取JS代码 即可获取对应的示例代码,注意:示例代码中包含此广告的app_idplacement_id

2.2.5 部署JS代码,发布网页,测试、上线。

将代码复制到自己网页源码的对应位置,并进行联调测试。在测试完成并确认无误后,发布包含广告代码的网页,上线广告。

3 H5 SDK接入规范

如果你的H5页面,可能同时使用多个优量汇广告(例如同时接入banner、插屏广告和模板广告),需要阅读接入流程规范,此规范是保证H5 SDK能够拉取多种类型广告的基本步骤,接入H5广告前,请先认真阅读此章节。完整的流程包括:申明全局命名空间 >> 广告位申明 >> 加载H5 SDK

3.1 H5 SDK接入步骤

接入H5 SDK前,请先阅读此图,接入过程有任何问题,可对照此图进行查找问题。

3.1.1 申明全局命名空间:

window.TencentGDT = window.TencentGDT || [];

3.1.2 广告位申明

广告位需要通过以Object的形式pushTencentGDT命名空间中,可以支持多个广告位push操作:

TencentGDT.push({
    placement_id: '11**99', // String,广告位id
    app_id: '11**00', // String,appid
    type: 'rewardVideo', // String,广告类型,请根据广告类型填写对应的type值
    display_type: 'banner',
    onComplete: function(res) { // Function,广告位初始化回调方法,已激励视频接入为例
        if(res.code == 0) {
            // 激励视频实例化,注意:插屏广告、模板广告方位为:renderAd
            var video = new TencentGDT.NATIVE.rewardVideoAd( function(res) {
                // 激励视频回调参数
                console.log(res);
            });
            // 激励视频加载方法
            video.loadAd();
            // 激励视频播放方法
            video.showAd();
        }
    }
});

API说明:

参数 类型 必要 说明
placement_id String 必填 广告位id
app_id String 必填
type String 必填 广告位类型,选项包括,原生模板:native、激励视频:rewardVideo
display_type String 选填 banner、插屏广告必须填写display_type,具体值见各个广告文档说明
onComplete Function 选填 广告回调方法,执行初始化、视频加载、视频播放相关的回调都在此方法回调捕获

type值:

display_type

注意:Android、iOS环境请分别选择imei和idfa规则上报。如果流量在QQ浏览器、QQ、微信环境中,可不用上报imei和idfa。

3.1.3 加载H5 SDK

(function () {
    var doc = document,
        h = doc.getElementsByTagName('head')[0],
        s = doc.createElement('script');
    s.async = true;
    s.src = '//qzs.qq.com/qzone/biz/res/i.js';
    h && h.insertBefore(s, h.firstChild)
})();

以上3.1.1 ~ 3.1.3的执行顺序不能改变,否则会导致广告初始化声明失败,以上步骤完成后,即可按照下列广告类型进行广告接入。

3.2 banner广告

访问banner广告接入

3.3 插屏广告

访问插屏广告接入

3.4 H5激励视频广告

访问H5激励视频广告

3.5 原生模板广告

访问原生模板广告

3.6 原生自渲染广告

访问原生自渲染广告

4 测试报错原因查找

4.1 JS报错

通过请求返回值ret查看出错情况(看最后3位数字):

返回 原因
104 adposcount为空/不是数字/太大/小于0
105 posid为空
106 count/posw/posh为空
107 posid无效/posw posh填写不符合广告位宽和高填写逻辑
118 posid无效/必填字段缺失

4.2 出现白屏

4.2.1 原生广告

提供了拉取广告的回调函数,开发者可以根据回调返回的状态码以及广告数据长度来判断广告拉取失败或者无广告返回,在这种情况下开发者可以自己选择重新调用拉取广告的接口或者自己渲染自己的广告进行填充。

4.2.2 插屏广告

插屏广告对拉取不到广告的情况不会弹出浮层进行广告渲染,体验上不会出现无广告填充的白屏现象。对开发者无影响。

5 收益优化建议

5.1 提高广告填充率

5.2 广告位设置建议


(本文完)

Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇