腾讯联盟 API 接入文档

关于文档

对有APP流量变现需求但由于各种原因无法嵌入腾讯广告联盟SDK的开发者，腾讯广告联盟提供基于广告播放API的合作方式。开发者应保证获得用户授权同意，由开发者收集并向腾讯提供如下字段。本文档详细介绍了广告播放API的运营对接流程和接口协议等内容。

背景知识

名词解释

• 开发者： 指腾讯广告联盟官网（以下简称联盟平台）的注册会员。用QQ号注册成功后系统会自动生成一个新的固定为12位数字的账号ID，这个ID是腾讯广告联盟识别开发者的唯一ID。

• 媒体： 指在联盟平台创建的媒体，这里媒体等价于应用的概念。创建媒体时获得的ID将成为应用ID，这个ID是腾讯广告联盟识别您应用的唯一ID。

• 广告位： 指在联盟平台为媒体创建的某种类型（开屏、原生、激励视频，从3.3版本开始，联盟api将不支持banner和插屏样式，需要继续使用该样式的开发者建议使用原生广告进行渲染或转接SDK）的广告位置。创建广告位时获得的ID将成为广告位ID，这个ID是腾讯广告联盟识别您广告位置的唯一ID。

技术规范

有关标准HTTP协议，可参考 RFC2616 或 维基百科-HTTP 。有关URL编码，可参考RFC3986或维基百科-Percent-encoding。有关JSON数据格式，可参考 JSON.ORG 或 维基百科–JSON 。

对接流程

流程介绍

前期准备： API合作以腾讯广告联盟运营人员（以下简称运营人员）邀请的方式发出，开发者在接受邀请后，需在运营人员指导下填写《API接入申请表》。

• 1.注册开户： 审核通过后，开发者需先在联盟平台注册成为会员，在审核过程中，即可联系运营人员获取《腾讯广告联盟广告播放API说明文档》。
• 2.开发联调： 开发者根据文档要求进行功能开发，开发完成后，先使用测试广告位进行联调。在此过程中如果有疑问，请联系运营人员。
• 3.审核验证： 联调成功后，开发者将预发布的APK包和开发者ID提供给运营人员进行验证广告样式，验证通过后，开通API权限。
• 4.灰度放量： 获得权限后，在联盟平台创建API接入的媒体和广告位，将广告请求中的测试广告位ID替换成新创建的，开始进行灰度放量。在灰度过程中，联盟运营人员会进行效果验证，验证通过，开始正式放量。验证未通过，需开发者根据优化建议做调整修改，完成后进行二次验证，仍未通过，将收回API权限推荐使用SDK合作。
• 5.正式上线： 灰度验证后，开始正式上线放量，开发者可以登录联盟平台查看流量收益情况。

注意事项

• 1.新流量请求限制： 为更好地了解您的流量、匹配更合适的广告，在新创建广告位流量上线初期，腾讯广告联盟会进行广告日请求量限制。当达到日请求量上限时，将无广告返回，且会有返回码提示，具体处理方式请参考附录广告请求返回码列表。
• 2.原生广告/激励视频广告接入提示： 在联盟平台创建广告位时，默认不能创建原生/激励视频广告位，如果开发者要接入原生/激励视频广告，需要联系运营人员沟通申请。

广告播放API

腾讯广告联盟后台服务（以下简称联盟后台）通过广告播放API对外提供广告请求和数据上报服务。该API包含如下四个接口，调用流程见下文广告播放时序图。

• 1.广告请求： 腾讯广告联盟支持两种方式请求广告。

  • a.开发者APP通过后台服务向联盟后台请求广告

    

  • b.开发者APP直接向联盟后台请求广告

    

强烈建议开发者通过后台服务请求广告。如果是想让APP直接请求广告，首选SDK接入方式，开发工作量小而且流量变现效果通常会更好。联盟后台后续可能会禁止APP直接发起广告请求。

• 2.曝光上报： APP将广告展示给用户后，APP必须实时、直接向联盟后台上报曝光，不允许通过开发者后台服务上报。

• 3.点击上报： 用户点击广告后，APP必须实时、直接向联盟后台上报点击，不允许通过开发者后台服务上报。

• 4.转化上报： 目前只对app下载类广告有意义，特指下载开始、下载完成、安装完成这3种转化行为的上报。转化行为发生后，APP必须实时、直接向联盟后台上报，不允许通过后台服务上报。

通信方式

联盟后台与外部调用方的基础通信协议采用HTTP协议和HTTPS协议。

超时时间

不考虑网络链路（调用方与联盟后台服务器之间的传输链路）时延，对99%的请求，联盟后台能在200ms内响应。广告请求超时时间建议设置1秒；其他接口建议设置较大的超时时间，比如10秒。

编码方式

若无特殊说明，所有输入参数、返回结果的字节编码均使用UTF-8（无BOM头)。

HTTP请求

• HTTP Method
  使用GET方法

• HTTP Header
  如果是由后台服务发起广告请求，则需要在HTTP请求头部填充如下字段；其它情况下无特殊请求头部字段要求。

• HTTP 请求数据
  请求数据放在URL查询字符串中，使用键值对形式（例如url格式为http://domain/path?name1=value1&name2=value2 ，其中“?”之后的部分是查询字符串）。查询字符串中每个参数的值（value1和value2）必须进行URL编码。

HTTP响应

• HTTP状态码
  不同接口在不同情况下会返回不同的HTTP状态码，在下文详细介绍每个接口时说明。

• HTTP Header
  无响应头部字段要求。

• HTTP响应数据
  响应数据（HTTP Response Body）如果不为空，均使用JSON格式

广告请求接口

开屏广告位必须实时请求广告（实时是指在广告位即将展示给用户或已经展示给用户时），不允许缓存广告；其他广告位可以预请求广告并缓存起来，然后在合适的时机将广告曝光。预请求广告可能产生广告预算不足等一系列问题，从而影响流量变现效果，建议所有类型广告位实时请求广告。

广告请求接口-请求地址

http://mi.gdt.qq.com/api/v3

广告请求接口-请求数据

可选参数填写原则：1. 首先保证取值正确；2. 在取值正确的前提下尽量填写。如不能获取，或不能保证取值正确性，则不填写，以免拉低流量质量，影响变现效果。

• pos JSON对象

• media JSON对象

• device JSON对象

注：

（1）对安卓设备请求，imei、imei_md5、android_id、android_id_md5、oaid至少要填写其中一个

（2）对于iOS设备请求，idfa、idfa_md5、10个设备信息字段(device_start_sec~time_zone)三者至少填写一个，如果无idfa和idfa_md5则10个设备信息字段都必填

• network JSON对象

• geo JSON对象

广告请求接口-请求示例

• android设备原生广告位请求

  GET
  http://mi.gdt.qq.com/api/v3?api_version=3.0&pos=%7B%22id%22%3A 8050018672826551%2C%22ad_count%22%3A2%7D&media=%7B%22app_id%22%3A%221104241296%22%2C%22app_bundle_id%22%3A%22com.test.android%22%7D&device=%7B%22os%22%3A%22android%22%2C%22os_version%22%3A%226.0.1%22%2C%22model%22%3A%22MI%204LTE%22%2C%22manufacturer%22%3A%22Xiaomi%22%2C%22device_type%22%3A1%2C%22screen_width%22%3A360%2C%22screen_height%22%3A640%2C%22orientation%22%3A0%2C%22imei%22%3A%22123456789009876%22%2C%22android_id%22%3A%229774d56d682e549c%22%2C%22android_ad_id%22%3A%22d725f723-86ea-466a-883d-5be2ca568241%22%7D&network=%7B%22connect_type%22%3A1%2C%22carrier%22%3A3%7D&geo=%7B%22lat%22%3A39925625%2C%22lng%22%3A116333285%2C%22coord_time%22%3A1473416991123%7D HTTP/1.1
  Host: mi.gdt.qq.com
  X-Forwarded-For: 14.17.22.35
  User-Agent: Mozilla/5.0 (Linux; U; Android 4.4.4; zh-cn; MI 4LTE Build/KTU84P) AppleWebKit/537.36 (KHTML, like Gecko)Version/4.0 MQQBrowser/5.8 Mobile Safari/537.36
  Referer: http://www.qq.com
  

• ios设备激励视频广告位请求（横屏状态）

  GET http://mi.gdt.qq.com/api/v3?api_version=3.0&pos={%22id%22:7010037942894023,%22ad_count%22:1}&media={%22app_id%22:%221104238667%22,%22app_bundle_id%22:%22com.test.ios%22}&device={%22os%22:%22ios%22,%22os_version%22:%2210.1.1%22,%22model%22:%22iPhone%205s%22,%22device_type%22:1,%22orientation%22:90,%22idfa%22:%22008A39D4-CF91-40F8-ADF0-E119F206AE6E%22}&network={%22connect_type%22:1,%22carrier%22:3}&geo={%22lat%22:39925625,%22lng%22:116333285,%22coord_time%22:1473416991123} HTTP/1.1
  Host: mi.gdt.qq.com
  X-Forwarded-For: 14.17.22.35
  User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12F70 Safari/600.1.4
  Referer: http://www.qq.com
  

广告请求接口-响应数据

响应的JSON数据包含三部分内容，分别是返回码ret、返回码描述msg和数据data，如下表所示。未在本文档中说明但出现在响应中的字段，是腾讯内部系统接口，随时可能变更，请勿使用。

• data JSON对象

• {pos.id} JSON对象

• list JSON数组元素(广告)

广告请求接口-响应示例

• 原生图文广告

HTTP/1.1 200 OK

{
    "ret":0,
    "msg":"",
    "data":{
        "8050018672826551":{
            "list":[
                {
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=bSVdor67lmXY5!eoxbZOOOOb_CQu1rpTvJWGM8AVi0E3iy!2VnzgHLzz_dIL6pq5Fi8LxPtJYIBFM2jYvVXbDGMGQrr63raQ_9tzhiFUUlAjs1Bg_LUzJYNcxaOA!5MG!MwjlLYc!2CUmeGx6oWfp!BidFhL1ZzybbRTGcbUT1LynM1imRxQGexJkjBDHquCv7szfLd_ThR0S1cAqtlAIQ&i=1&os=2&datatype=json",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=bSVdor67lmXY5!eoxbZOOOOb_CQu1rpTvJWGM8AVi0E3iy!2VnzgHLzz_dIL6pq5Fi8LxPtJYIBFM2jYvVXbDGMGQrr63raQ_9tzhiFUUlAjs1Bg_LUzJYNcxaOA!5MG!MwjlLYc!2CUmeGx6oWfp!BidFhL1ZzybbRTGcbUT1LynM1imRxQGexJkjBDHquCv7szfLd_ThR0S1cAqtlAIQ&jtype=0&i=1&os=2&asi=%7B%22mf%22%3A%22Xiaomi%22%7D&acttype=0&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D",
                    "interact_type":0,
                    "crt_type":11,
                    "title":"链家717，租房换新季！",
                    "description":"两室一厅两卫+大阳台，家用电器齐全，佣金每1000减200！",
                    "img_url":"http://pgdt.gtimg.cn/gdt/0/DAAPzYQAUAALQABZBZXLOKDKDSAgqS.jpg/0?ck=bb5fd85d2dfe45d89c73d52f6391905a",
                    "img2_url":"http://pgdt.gtimg.cn/gdt/0/DAAPzYQAEsAEsAAUBZXK6GCzdJLQFu.jpg/0?ck=9807f69989ad965535fae4448e63dbd0"
                },
                {
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=!mq3jem6jprY5!eoxbZOODQykDLHprRMH65OvFKKvnuxmHadHDFZmHxCVhJgx4qdXJfEF3BzMO7ycM5WNA6vqTBcYqdnce!KjHDlc7j9XMPkPH7zXU5N9rEmO6tBdDvcoy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuOgpnXINM0Gbap7qjZMAzQ2LWZpHEZeu_Ix0wRx3Df14w&i=1&os=2&datatype=json",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=!mq3jem6jprY5!eoxbZOODQykDLHprRMH65OvFKKvnuxmHadHDFZmHxCVhJgx4qdXJfEF3BzMO7ycM5WNA6vqTBcYqdnce!KjHDlc7j9XMPkPH7zXU5N9rEmO6tBdDvcoy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuOgpnXINM0Gbap7qjZMAzQ2LWZpHEZeu_Ix0wRx3Df14w&jtype=0&i=1&os=2&asi=%7B%22mf%22%3A%22Xiaomi%22%7D&acttype=1&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D",
                    "conversion_link":"http://t.gdt.qq.com/conv/alliance/api/conv?client=6&action_id=__ACTION_ID__&click_id=__CLICK_ID__&product_id=1106228530",
                    "interact_type":1,
                    "crt_type":11,
                    "title":"沙城传说",
                    "description":"经典传奇回归，开局一把木剑，打蜈蚣爆出屠龙刀，系统回收，过瘾",
                    "img_url":"http://pgdt.gtimg.cn/gdt/0/DAAEEh2AUAALQABQBZXZivCx-g1rXm.jpg/0?ck=5422e0280124288729a93a024896e7c5",
                    "img2_url":"http://pgdt.gtimg.cn/gdt/0/DAAEEh2AEsAEsAAXBZXZiXDY-kMKbV.jpg/0?ck=c6066c8bae5de0fad07ab0739852ea5f"
                }
            ]
        }
    }
}

• 三小图网页类广告

HTTP/1.1 200 OK

{
    "ret":0,
    "msg":"",
    "data":{
        "7010946296282620":{
            "list":[
                {
                    "ad_id":"78064987",
                    "impression_link":"http://v.gdt.qq.com/gdt_stats.fcg?viewid=0UK1EIN9ibAzpwc26RfjJ1hUXwGgvOOvZLGy5ow!97_x!pE55QuV6QyA_KDCDBfW!u51XavIXZIS9IrLQAFrLyw7YqQr9r3w2tpmmqFlSoQ3a8trEKpgF1SgJdP_XP8aSjKJxWNbnuqC4yl7lRBTkB9ATQDfLYSj0wn0LSMH246WBhka14_39Xlm!NaokVnYq!opvRtU02dV5utkxBPFAH1UrPg6Clv_sC6qfM9iD48&i=1&os=1&datatype=json&xp=3",
                    "click_link":"http://c.gdt.qq.com/gdt_mclick.fcg?viewid=0UK1EIN9ibAzpwc26RfjJ1hUXwGgvOOvZLGy5ow!97_x!pE55QuV6QyA_KDCDBfW!u51XavIXZIS9IrLQAFrLyw7YqQr9r3w2tpmmqFlSoQ3a8trEKpgF1SgJdP_XP8aSjKJxWNbnuqC4yl7lRBTkB9ATQDfLYSj0wn0LSMH246WBhka14_39Xlm!NaokVnYq!opvRtU02dV5utkxBPFAH1UrPg6Clv_sC6qfM9iD48&jtype=0&i=1&os=1&acttype=0&s=%7B%22req_width%22%3A%22__REQ_WIDTH__%22%2C%22req_height%22%3A%22__REQ_HEIGHT__%22%2C%22width%22%3A%22__WIDTH__%22%2C%22height%22%3A%22__HEIGHT__%22%2C%22down_x%22%3A%22__DOWN_X__%22%2C%22down_y%22%3A%22__DOWN_Y__%22%2C%22up_x%22%3A%22__UP_X__%22%2C%22up_y%22%3A%22__UP_Y__%22%7D&xp=3",
                    "interact_type":0,
                    "crt_type":7,
                    "title":"翡翠原厂地直供，高性价比",
                    "description":"买翡翠的注意！这个APP源头直供，比实体店便宜一半",
                    "img_list":[
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAKBb0aNwCQwwHkGo.jpg/0?ck=6106dfc36bee5dd8dec60b6d60e2db43",
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAbBb0aNzBvw07kQd.jpg/0?ck=a31a8c84ca8eae23ba4e961d0b3f41d4",
                        "http://pgdt.ugdtimg.com/gdt/0/DAAe7Y2ADkACWAAdBb0aN2AqTuDmq3.jpg/0?ck=017d4621bee5af0afaacddda0135b72e"
],
                    "app_id":982906456
                }
            ]
        }
    }
}

• 激励视频网页类广告

具体情况请以线上返回为主

广告请求接口- 响应处理流程

HTTP响应状态码为200并且响应数据中返回码ret=0时，表示请求广告成功。当HTTP响应状态码不是200时，联盟后台建议立即发起广告请求重试但最多只能重试一次；其他异常情况，不允许重试。具体处理流程如下：

曝光上报

当广告展示给用户并且满足腾讯广告联盟曝光有效性标准时，开发者需要实时将本次曝光事件上报给联盟后台。曝光有效性标准如下：

• 广告展示区域的50%以上像素点在用户屏幕上并且持续可见时间超过1秒钟。

获取到的广告尽力曝光，不允许刻意舍弃某种类型的广告。每条广告只能曝光一次。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价，从而降低流量变现效果：

• 1.对一次广告播放事件，没有曝光上报
• 2.对一次广告播放事件，重复曝光上报
• 3.对一次广告播放事件，曝光上报与广告请求时间间隔太大
• 4.广告曝光率（曝光数/返回广告数）显著偏离正常水平

曝光上报-请求地址

曝光上报URL直接使用广告请求响应数据中的impression_link字段，该字段已经包含了完整的请求地址和请求数据（已经过URL编码），禁止开发者做任何修改。

曝光上报-请求数据

使用impression_link字段，无需开发者填写。

曝光上报-请求示例

GET http://v.gdt.qq.com/gdt_stats.fcg?viewid=JcOh4K3LVtyM36FJYvAKAF_yL7FjDsqIvTv5Okb!OqmRVZVS8grRgfb8mE9jYoS3BM_S5FP!mBZFagqd3pitSIXFLugPNNM75APKz15fpCA7Nk4H9DL2Ahm1KyByHV8GH2Hze4h6XRewMVpuIwReDjNtbh_alplvlZaYU3BNpH6EwUQ6YS9AO4d80Y!HEso908m3ktLbFLe6wzKcjP!ZTEGfycQ1SVBsYoeco3kALE8Q2OLoI!jjzgUFAII8BY_TUXTHvNtw!0BFSBqfcPivGUYAGavN3CsGjlNHDLISkrq4M4nBfKMOdhWSjiBSChpFUgxTRRG8Y64&datatype=json HTTP/1.1
Host: v.gdt.qq.com

曝光上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

曝光上报-响应示例

HTTP/1.1 200 OK

{
 "ret":0,
  "msg":""
}

曝光上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起转化上报重试但最多只能重试一次；其他异常情况，不允许重试。

视频播放信息上报

对于视频广告，开发者需要在视频播放结束时，上报视频播放信息。在一次广告播放事件中用户可能多次播放视频，每次视频播放结束时，都要上报一次播放信息。以下情况可能导致联盟后台对广告播放事件不计费并影响对流量质量的评价，从而降低流量变现效果：

• 1.对一次广告播放事件，上报了错误的视频播放信息
• 2.对一次广告播放事件，视频播放信息上报与广告请求时间间隔太大
• 3.视频播放率（视频播放数/曝光数）显著偏离正常水平

视频播放信息上报-请求地址

视频播放信息上报URL需要开发者对广告请求响应数据中video_view_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

视频播放信息上报-请求数据

video_view_link中需要替换的宏：

视频播放信息上报-请求示例

GET http://vr.gdt.qq.com/gdt_stats.fcg?&datatype=json&viewid=3fOzNrVLMUCYOAUpt_U94oWRGcW_STX5fYS7sdOMs46chbddtzrkhTTd6kAvaNL5L6DoWzgO5VXF83EaF!O5MNk4vq!Un!q1uRjaYt6WQ5y_Fen1gKkVr6f4jp8u9bh1oy5h9Q6V6NoZu3G8BRBT1vxgY5E3IlquQhNO0DqSWuNYHu2KUFcRnQerHewVpZwDLWZpHEZeu_Jiadr1uWzZAA&video=%7b%22vt%22%3a%2215%22%2c%22bt%22%3a%220%22%2c%22et%22%3a%225%22%2c%22bf%22%3a%221%22%2c%22ef%22%3a%220%22%2c%22pp%22%3a%221%22%2c%22pa%22%3a%221%22%2c%22pb%22%3a%221%22%2c%22ps%22%3a%220%22%7d HTTP/1.1
Host: v.gdt.qq.com

视频播放信息上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

视频播放信息上报-响应示例

HTTP/1.1 200 OK

{
  "ret":0,
  "msg":""
}

视频播放信息上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起视频播放信息上报重试但最多只能重试一次；其他异常情况，不允许重试。

点击上报

当广告交互区域（对大部分广告，可以是整个广告所在区域；对某些广告，如视频广告，可以是一个局部区域，比如一个出现在视频下方的“查看详情”按钮，参考附录广告渲染样式示例视频广告渲染示例）被用户点击时，开发者需要实时将本次点击事件上报给联盟后台并尽力引导用户到达广告目标地址（广告推广商品的网页地址或APP下载地址）。对联盟后台点击上报接口的1次调用，即可实现点击事件上报，并从响应数据中获得广告目标地址。用户发生N次点击则进行N次点击上报，禁止用户点击一次，但进行多次点击上报。以下情况可能导致联盟后台对广告播放事件不计费或影响>对流量质量的评价，从而降低流量变现效果：

• 1.对一次广告播放事件，用户点击了广告但没有点击上报
• 2.对一次广告播放事件，点击上报与广告请求时间间隔太大
• 3.广告点击率（点击数/曝光数）显著偏离正常水平

点击上报-请求地址

点击上报URL需要开发者对广告请求响应数据中click_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

点击上报-请求数据

开发者在广告点击时需要捕获用户点击坐标，该值将在联盟后台用来帮助提升用户点击率，从而提高开发者收入。
如下图所示，坐标是指相对于实际广告位（即完整广告容器）左上角的坐标，箭头方向为正坐标方向，其中针对全屏类广告，实际广告位大小即等于屏幕大小。

注：Android端坐标单位需使用 逻辑像素(dp) = 物理像素(px) / 屏幕密度(dpi)，以消除不同分辨率手机屏幕导致的坐标差异。

click_link中以下宏都要替换，如无法获取坐标时，请替换为-999。

点击上报-请求示例

GET http://c.gdt.qq.com/gdt_mclick.fcg?viewid=JcOh4K3LVtyM36FJYvAKAF_yL7FjDsqIvTv5Okb!OqmRVZVS8grRgfb8mE9jYoS3BM_S5FP!mBZFagqd3pitSIXFLugPNNM75APKz15fpCA7Nk4H9DL2Ahm1KyByHV8GH2Hze4h6XRewMVpuIwReDjNtbh_alplvlZaYU3BNpH6EwUQ6YS9AO4d80Y!HEso908m3ktLbFLe6wzKcjP!ZTEGfycQ1SVBsYoeco3kALE8Q2OLoI!jjzgUFAII8BY_TUXTHvNtw!0BFSBqfcPivGUYAGavN3CsGjlNHDLISkrq4M4nBfKMOdhWSjiBSChpFUgxTRRG8Y64&jtype=0&i=1&acttype=1&s=%7B%22req_width%22%3A%22250%22%2C%22req_height%22%3A%22100%22%2C%22width%22%3A%22300%22%2C%22height%22%3A%22120%22%2C%22down_x%22%3A%22100%22%2C%22down_y%22%3A%2250%22%2C%22up_x%22%3A%22100%22%2C%22up_y%22%3A%2250%22%7D HTTP/1.1
Host: c.gdt.qq.com

点击上报-坐标获取

1.Android端
Android端的按下、抬起坐标原点在广告容器左上角，建议重写广告容器ViewGroup的dispatchTouchEvent方法获取按下、抬起的点击坐标，然后return super.dispatchTouchEvent(event)，不会影响原来dispatchTouchEvent方法逻辑。
以上方的点击坐标示意图为例，重写绿色部分广告容器的dispatchTouchEvent方法，容器内触摸事件坐标均可以获取，当红色按钮点击事件触发时上报刚刚获取的点击坐标。

Android代码示例

// 保存按下、抬起坐标
int startX,startY,endX,endY;
// 重写广告容器ViewGroup的dispatchTouchEvent方法，获取按下、抬起坐标
@Override
public boolean dispatchTouchEvent(MotionEvent event) {
    switch (event.getAction()) {
        // PxUtil.pxToDp是伪代码，需要开发者实现
        case MotionEvent.ACTION_DOWN:
            // 获取按下的坐标，转换成逻辑像素(dp)
            startX = PxUtil.pxToDp(event.getX());
            startY = PxUtil.pxToDp(event.getY());
            break;
        case MotionEvent.ACTION_UP:
            // 获取抬起的坐标，转换成逻辑像素(dp)
            endX = PxUtil.pxToDp(event.getX());
            endY = PxUtil.pxToDp(event.getY());
            break;
    }
    return super.dispatchTouchEvent(event);
}
// 点击事件触发时上报坐标
public void onBtnClick(View view) {
    ......
    // reportClickCoordinate是伪代码，需要开发者实现
    reportClickCoordinate(startX, startY, endX, endY);
}

2.iOS端
iOS的按下、抬起坐标需要通过[UITouch loactionInView:]方法来进行坐标转换，即在被触发点击事件的UITouch对象的对应方法。其中，locationInView的传入参数为广告容器，不论是半屏广告还是全屏广告，即上图中绿色部分。
以上方的点击坐标示意图为例，如果事件绑定在红色按钮区，需要取到红色按钮的UITouch对象，触发对应的loactionInView方法获取坐标。

iOS代码示例

- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
{
    [super touchesBegan:touches withEvent:event];
    // 按下坐标获取方法
    CGPoint beginPoint = [[touches anyObject] locationInView:self.adView]; // 这里的View填写广告的View。如果是半屏广告就填写半屏的View，如果是全屏广告就填写全屏广告的View
}

- (void)touchesEnded:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
{
    [super touchesEnded:touches withEvent:event];
    // 抬起坐标获取方法
    CGPoint endPoint = [[touches anyObject] locationInView:self.adView];  // 这里的View填写广告的View。如果是半屏广告就填写半屏的View，如果是全屏广告就填写全屏广告的View

    // 广告距离屏幕左上角的坐标获取方法
    CGRect adViewToScreenOriginRect = [self.adView convertRect:self.adView.frame toView:nil];
}<

点击上报-响应数据

优量汇API目前已支持在广告请求接口响应数据中返回广告跳转链接，不依赖点击上报响应数据，建议开发者使用最新版本。

针对不同类型广告的点击交互处理流程，可参考附录广告点击交互处理流程，无需参考依赖点击上报响应进行跳转的逻辑。

对不同交互类型的广告，点击上报接口返回的数据不同：

• 1.对于交互类型是打开网页的广告（广告请求响应interact_type=0），目标地址是网页，点击上报接口返回HTTP 302跳转，开发者在应用内或外部浏览器中展示网页。目前ios设备上的所有广告和安卓设备上部分广告是打开网页类型的广告（推广ios APP的广告跳转到Apple App Store的APP详情页地址）。从保护用户体验和广告转化效果角度考虑，建议安卓设备使用webview或内置浏览器打开，ios设备使用webview或SafariViewController打开。
  注意：有些网页在打开后，会尝试唤起广告主APP以引导用户发生转化行为。强烈建议开发者使用的浏览器或webview支持唤起外部APP（ios设备上Safari浏览器和系统webview、SafariViewController已支持；安卓上浏览器和webview支持情况差异较大）。广告转化效果会影响腾讯广告联盟对流量质量的评
  价，从而影响流量变现效果。
• 2.对于交互类型是APP下载的广告（广告请求响应interact_type=1），目标地址是APP下载地址，点击上报接口返回响应数据，开发者需要解析数据来获取APP下载地址，以及进行后续的转化数据上报。目前APP下载类广告只出现在安卓设备上。从保护用户体验和广告转化效果角度考虑，建议：非wifi环境
  下弹出下载确认框，在用户确认后再发起下载；wifi环境下则直接下载。响应数据是JSON格式，包含两部分内容：返回码ret和数据data，如下表所示：

• data JSON对象

点击上报-响应示例

• 交互类型是打开网页（广告请求响应interact_type=0）

HTTP/1.1 302 Moved Temporarily
Location: http://zt.jd.com/ad/appjump.shtml?turl=http%3A%2F%2Fsale.jd.com%2Fm%2Fact%2FZhiH2XuDdcqoK.html&platform=2&qz_gdt=vwgbqwdsaaah7seyb62q

• 交互类型是APP下载（广告请求响应interact_type=1）

HTTP/1.1 200 OK

{
    "ret":0,
    "data":{
        "dstlink":"http://imtt.dd.qq.com/16891/335E360BFA5B5127F12E43BC480BE11A.apk?fsname=com.sohu.newsclient_5.7.2_112.apk&csr=4d5s&_gdt_ma_cdn_cb=1&qz_gdt=jarbawhga4akgqsrylma&appid=100898297",
        "clickid":"jarbawhga4akgqsrylma"
    }
}

点击上报-响应处理流程

当发生以下情况时，联盟后台建议立即发起点击上报重试但最多只能重试一次；其他异常情况，不允许重试。

• 1.广告是APP下载类广告并且HTTP响应状态码不是200
• 2.广告是打开网页类广告并且HTTP响应状态码不是302

转化上报

• 对于APP下载类型广告（广告请求响应字段interact_type=1），腾讯广告联盟需要追踪下载效果，包括下载开始率、下载完成率和安装率，所以需要APP上报下载开始、下载完成和安装完成。
• 对于应用直达类型广告（广告请求响应字段customized_invoke_url存在时），腾讯广告联盟需要追踪应用直达效果，包括尝试唤起APP率和唤起APP成功率，所以需要APP上报应用直达广告尝试唤起APP和应用直达广告唤起APP成功。
• 对于APP场景下的应用直达类型广告（广告请求响应字段interact_type=1且customized_invoke_url存在时），腾讯广告联盟还需要追踪APP应用安装率（应用已安装/应用未安装/无法获取应用安装信息），所以还需要APP上报应用已安装/应用未安装/无法获取应用安装信息。
• APP及时准确地上报这些转化行为，会正面影响腾讯广告联盟对流量质量的评价，从而提高流量变现效果；反之，如果不上报或虚假上报，会负面影响腾讯广告联盟对流量质量的评价，从而降低流量变现效果。

转化上报-请求地址

转化上报URL需要开发者对广告请求响应数据中conversion_link字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

转化上报-请求数据

conversion_link中需要替换的宏：

转化上报- 请求示例

下载开始
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=5&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

下载完成
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=7&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

安装完成
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=6&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用直达广告尝试唤起APP
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=245&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用直达广告唤起APP成功
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=246&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用已安装
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=247&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

应用未安装
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=248&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

无法获取应用安装信息
Get http://t.gdt.qq.com/conv/alliance/api/conv?action_id=249&client=6&product_id=10332186&click_id=r7p3mvyfaaaiubiabp5a HTTP/1.1
Host: t.gdt.qq.com

转化上报-响应数据

响应数据是JSON格式，包含两部分内容：返回码ret和返回码描述msg，如下表所示。

转化上报-响应示例

HTTP/1.1 200 OK

{
  "ret":0,
  "msg":""
}

转化上报-响应处理流程

HTTP响应状态码为200并且ret=0时，表示上报成功；其他情况均表示失败。当HTTP响应状态码不是200时，联盟后台建议立即发起转化上报重试但最多只能重试一次；其他异常情况，不允许重试。

竞胜上报

• 对于以API形式接入的流量，腾讯广告联盟需要回收广告竞胜价格。
• 及时准确地上报这些转化行为，会正面影响腾讯广告联盟对流量质量的评价，从而提高流量变现效果；反之，如果不上报或虚假上报，会负面影响腾讯广告联盟对流量质量的评价，从而降低流量变现效果。

竞胜上报-请求地址

竞胜上报URL需要开发者对广告请求响应数据中win_notice_url字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

竞胜上报-请求数据

win_notice_url中需要替换的宏：

竞胜上报-响应说明

开发者不必等待竞胜url的返回。正常情况下，HTTP响应状态码为200；其他异常情况，不允许重试。

竞败上报

• 对于以API形式接入的流量，腾讯广告联盟需要回收广告竞败相关信息。
• 及时准确地上报这些信息，会正面影响腾讯广告联盟对流量质量的评价，从而提高流量变现效果；反之，如果不上报或虚假上报，会负面影响腾讯广告联盟对流量质量的评价，从而降低流量变现效果。

竞败上报-请求地址

竞败上报URL需要开发者对广告请求响应数据中loss_notice_url字段进行宏替换后得到。该字段包含了请求地址和部分请求数据（已经过URL编码），开发者需要进行宏替换将请求数据补充完整。

竞败上报-请求数据

loss_notice_url中需要替换的宏：

竞败上报-响应说明

开发者不必等待竞败url的返回。正常情况下，HTTP响应状态码为200；其他异常情况，不允许重试。

测试联调

联调说明

• 1.开发者从广告请求联调地址test.mi.gdt.qq.com/api/v3拉取广告。
• 2.开发者需要遍历测试“测试联调的广告位ID”中相应广告位类型下列出的所有广告位，对每个广告位：
  • a.测试每个广告请求参数的所有取值情况
  • b测试对各种类型的广告的渲染情况
  • c.测试对各种类型的广告的曝光上报、点击上报和转化上报情况
• 3.若测试时无法请求到APP下载类广告，可以将请求connect_type参数的值设成1(wifi)。但在线上环境务必根据真实联网方式填写connect_type参数。
• 4.注意：测试联调环境有QPS和日请求总量限制，请合理使用。

测试联调的广告位ID

附录

API基础数据类型定义

开屏广告位宽和高填写逻辑及渲染建议

• 1.开屏广告位width和height的可能取值见下表。具体填写逻辑，建议根据用户屏幕实际宽高进行选择，对于大尺寸的广告位宽和高，返回的图片会更清晰，图片文件体积一般也会更大。
• 2.渲染建议：由于手机屏幕尺寸比例众多，为保证渲染效果，建议对开屏渲染采用如下方法；
  拿到素材后，以屏幕最上方中间为对齐基准，等比例缩放素材至宽度和屏幕宽度相同，并全屏铺开展示，铺开后，如果：
  • 1.素材高度大于屏幕高度时，裁剪广告素材底部，使素材宽高和屏幕宽高一致
  • 2.素材高度小于屏幕高度时，则将素材等比缩放至高度和屏幕高度相同，对称裁剪素材两侧，使素材宽高和屏幕宽高一致

ios设备型号取值列表

广告请求返回码列表

当无广告返回时，对照错误码，首先检查填写逻辑，常见问题如下：

• 1.必填参数未填写
• 2.参数数据类型不正确
• 3.参数取值不合法。

具体返回错误码含义说明可点击连接查询

广告渲染样式示例

应用直达广告处理逻辑

权限申请

应用直达广告是一种特殊形式的广告形式。需要开发者具有一定的处理能力才能确保直达率满足平台的要求。因此，此类广告只针对部分开发者开放权限，并需要配合完成审核验证，才能准许播放。具体的申请方式，可与联盟对接运营接口人联系获取。

请求处理

在请求环节，pos JSON对象中的deep_link_version字段需要为必填，只有必填的情况下才可能请求到应用直达广告。
在响应环节， list JSON数组元素（广告）中的3个字段需要处理：

• customized_invoke_url：应用直达的url
• package_name：安卓情况下app广告的包名。
• relation_target：app广告安装定向情况，让开发者知道这是否是一条广告主要求的安装定向广告。

应用广告过滤处理

应用直达类广告为保证直达率，广告主往往会选择已安装或未安装定向，那么开发者需要结合这个定向情况以及app广告的包名，来检测用户当时手机上是否安装了此款app，如果符合预期则展示广告，否则需要将广告过滤，如果原生样式有多条广告请求则展示下一条广告，其他样式则重新发起请求。重新发
起请求时建议使用last_ad_ids接口，过滤掉上次拉取的广告，避免再次请求拉到相同的广告。

示例：

• 当relation_target取值为1时，说明广告主定向的是未安装广告app的用户，此时开发者检测如果用户安装了“package name”的应用，则过滤掉广告，展示下一条返回的广告（原生样式）或重新发起请求（其他样式）。如果确实手机上没有安装“package name”的应用，则可以正常曝光。
• 当relation_target取值为2时，说明广告主定向的是已安装广告app的用户，此时开发者检测如果用户安装了“package name”的应用，则可以正常曝光。如果确实手机上没有安装“package name”的应用， 则过滤掉广告，展示下一条返回的广告（原生样式）或重新发起请求（其他样式）。
• 当relation_target取值为0时，不用做任何处理。

点击处理

在响应环节， list JSON数组元素（广告）中的customized_invoke_url 是应用直达的url。当用户发生点击时，需要正常进行点击的上报。但是拿到响应后的处理逻辑与普通广告不同。
开发者需要在点击上报后，直接处理customized_invoke_url。当唤起目标app成功时，正常。当唤起目标app失败时，则使用点击响应data JSON对象的dstlink进行跳转。

转化处理

应用直达类广告存在唤起目标app成功及失败2种情况。需要使用点击响应中的data JSON对象的clickid进行上报：

• 当尝试唤起目标app时，进行一次尝试上报：conversion_link的__ACTION_ID__宏替换为245。
• 当唤起目标app成功时，进行一次成功上报：conversion_link的__ACTION_ID__宏替换为246。

上报正常的情况下，尝试上报的次数-唤起成功的次数=唤起失败的次数。

测试联调

测试联调时，针对开通了应用直达类广告权限的开发者，除了常规的测试联调外，需要额外进行上文中广告过滤处理、点击处理和转化处理中要求的测试。

厂商应用商店下载类广告处理逻辑

请求处理

在请求环节，请求参数中的 support_app_store 字段需要为必填，只有必填的情况下才可能请求到厂商应用商店下载类广告。
在响应环节，list JSON数组元素（广告）中的1个字段需要处理：

• market_url：厂商应用商店下载页url。

点击处理

在响应环节，list JSON数组元素（广告）中的 market_url 是厂商应用商店下载页面的url。当用户发生点击时，需要正常进行点击上报后，直接处理market_url，跳转至厂商应用商店内页面。

测试联调

测试联调时，需针对上述请求处理、厂商应用商店下载页面url的调起、点击处理中的要求进行测试。

微信小程序/小游戏广告处理逻辑

微信小程序/小游戏广告是指用户点击广告后，将跳转至微信打开微信小程序/小游戏，在微信内部发生后续的行为转化。优量汇新版本API协议文档已支持微信小程序/小游戏广告，开发者可按照以下方式接入微信小程序/小游戏广告。

前置条件

开发者接入微信小程序/小游戏广告前，需要

• 进入微信开放平台创建移动应用
• 应用创建完成后，在微信开放平台获取到相应的 AppID 和 Universal Links（仅iOS端需要Ulink）
• 在开发者APP内嵌入最新版微信openSDK，详细方法及资源详见微信开放文档
• 在优量汇开发者平台，将微信开放平台填写的 AppID 和 Universal Links 与当前应用进行关联

请求参数

在请求环节，device JSON对象中的下列字段（均可通过微信openSDK提供的接口获取到）需要为必填：

1.Android端

• wx_api_ver：用户微信内SDK版本
• opensdk_ver：微信 open SDK 版本

2.iOS端

• wx_installed：用户是否已安装微信
• opensdk_ver：微信 open SDK 版本

当open SDK版本、微信版本符合版本校验的要求时，可能请求到微信小程序/小游戏广告。

响应字段

在响应环节，list JSON数组元素（广告）中的2个字段需要处理：

• wechat_app_username：小程序原始id
• wechat_app_path：拉起小程序页面的可带参路径

开发者可调用open SDK并填写上述参数后，调起微信进入对应小程序页面，其中调用open SDK需要的字段 拉起小程序的类型 miniProgramType 默认填写0（正式版），因此不包括在响应字段内。

调用openSDK跳转微信小程序的具体方式可参考iOS流量指引、Android流量指引。

广告点击交互处理流程

请求接口响应返回相关URL说明

• customized_invoke_url： 应用直达url，点击后调起广告主应用；请求环节pos JSON对象中 deep_link_version 字段等于1时，可能会返回 customized_invoke_url，否则不返回。
• universal_link： iOS Universal Link，点击后调起广告主应用；iOS端可能会返回 universal_link。
• market_url： 厂商应用商店下载页url，点击后跳转应用商店进行下载；请求参数中 support_app_store 字段等于1时，可能会返回 market_url，否则不返回。
• package_url： 应用下载url，点击后直接下载应用；APP下载类广告（interact_type=1）广告必定返回。
• landing_page_url： 落地页url，点击后跳转对应落地页；所有广告必定返回。

不同类型广告返回的URL

注：
(1) 广告请求响应 interact_type=0 是打开网页类广告，interact_type=1 是APP下载类广告。
(2) iOS设备上所有广告都是打开网页类广告。

点击交互处理逻辑

1.Android端

(1) 整体逻辑

(2) APP下载类广告（interact_type=1）

• 跳转url优先级：customized_invoke_url > market_url > package_url > landing_page_url
• 媒体根据支持的跳转类型及返回的相关字段，按上述优先级进行跳转处理
• 针对应用直达广告（customized_invoke_url存在），调用customized_invoke_url字段调起应用，调起失败调用landing_page_url进行兜底。
• 针对非应用直达广告，支持厂商应用商店下载时（market_url存在），优先调用market_url跳转厂商应用商店下载页面进行app下载。
• 不支持厂商应用商店下载时可选择调用package_url，优量汇要求开发者调用package_url下载应用前，配合使用app_info_url等字段，通过弹窗等形式向用户展示应用名称、版本等应用相关信息，提示用户是否确认进行下载。
• 不支持直接下载应用时，调用landing_page_url跳转落地页。

(3) 打开网页类广告（interact_type=0）

• 跳转url优先级：customized_invoke_url > landing_page_url
• 媒体根据支持的跳转类型及返回的相关字段，按上述优先级进行跳转处理。
• 针对应用直达广告（customized_invoke_url存在），调用customized_invoke_url字段调起应用，调起失败调用landing_page_url进行兜底。
• 针对非应用直达广告，调用landing_page_url跳转落地页。

2.iOS端

(1) 整体逻辑

(2) 打开网页类广告（interact_type=0）

• 跳转url优先级：universal_link > customized_invoke_url > landing_page_url
• 媒体根据支持的跳转类型及返回的相关字段，按上述优先级进行跳转处理。
• universal_link字段存在时，优先调用universal_link字段调起应用，调起失败调用landing_page_url进行兜底
• universal_link字段不存在、customized_invoke_url字段存在时，调用customized_invoke_url字段调起应用，调起失败调用landing_page_url进行兜底
• universal_link和customized_invoke_url字段均不存在时，调用landing_page_url跳转落地页。