腾讯优量汇 Media API 接入文档

Version: 1.1.15

法律声明

对需要对接腾讯优量汇（以下简称优量汇）Media API的客户，优量汇提供此文档作为对接的指引文档。未经优量汇书面许可，不得以任何形式向第三方披露、泄露有关本文档的任何内容。优量汇拥有修改、调整、增补本文档的权利，并在法律允许范围内对本文档拥有最终解释权。

版本管理

本API文档目前统一为1.1.15版本，所有接口于2020年9月11日统一升级为1.1版本，其中，

• 媒体创建接口和修改接口、报表接口、图片接口1.1版本均兼容1.0版本；
• 广告位创建接口和修改接口1.1版本不兼容1.0版本，1.0版本不再维护，请开发者尽快将广告位创建接口和修改接口升级到1.1版本。

更新日志

重要知会

1.1.15版本变更关键点

• 7个广告场景下细分三级场景点 附录10. 广告三级场景点与场景映射关系；
• 创建广告位时可以使用场景（scene）或者三级场景点（position_scene_pro_3）设置广告位场景，场景参数必须二选一；使用场景时会默认填写三级场景点，默认值映射广告场景默认三级场景点。
• 7个广告场景的内容与定义做了调整，详情见术语介绍部分 。

1.1.14版本变更关键点

• 创建广告位支持平台模板渲染2.0 模板版本生成规则；平台模板渲染2.0支持模板类型多选、素材类型多选。
• 不支持平台模板渲染的自定义模板（包括：新建广告位、编辑广告位）

1.1.12版本变更关键点

• 新增测试媒体、测试广告位的功能，需要开通白名单。白名单申请，请在线联系优量汇客服。
• 测试媒体的创建，只支持操作系统=APP类型，即os参数仅支持1-Android, 2-iOS。
• 测试广告位的创建，只支持接入方式=SDK类型，即ad_pull_mode仅支持SDK，参见附录#接入方式。

1.1.5版本变更关键点

• 查询报表接口：增加Content-Type格式要求为application/json；不再支持multipart/form-data格式；请开发者做相应调整。

1.1.3版本变更关键点

• 广告场景替代广告位类型的概念，开发者可根据自身需求创建不同的广告场景下的广告位。广告场景与广告位类型的映射关系参见附录5
• 广告位模块切换：
  • 对外发布的文档更新为新接口；
  • 旧接入的开发者，新旧两套接口都支持调用；
  • 新接入的开发者，仅支持新接口调用；
  • 新接口创建和更新的请求body改为json格式；
  • 1.0版本旧接口不再维护升级，后续下线；
• 目前报表模块依然提供按照不同广告位类型的广告效果数据，后续提供按照不同广告场景的广告效果数据；

1.1.1版本变更关键点

• Media API中过去以mediumid和app_id两个参数均指代媒体id，为了减少混淆进行了优化，统一使用app_id作为媒体id的唯一标识，提醒开发者注意并修改：
  • 识别媒体id只需要以app_id为准；
  • app_id值与以前mediumid值是不同的值；

1. 关于文档

流量主可以通过对接Media API拥有强大的系统管理能力，更便捷地进行流量管理及快速对接广告统计数据，帮助流量主提升流量变现效率。
Media API提供的功能包含以下部分：

• 媒体模块：创建媒体、修改媒体
• 广告位模块：创建广告位、修改广告位
• 报表模块：查询广告效果数据

2. 背景知识

2.1 术语介绍

• 媒体：包括移动应用（APP）和移动网站；

• 旧广告场景定义：

  • 开屏：APP开启后全屏沉浸式展示广告
  • 动态信息流：广告与APP内容高度自然融合的信息流广告
  • 激励视频：用户通过体验某项服务以获取应用内奖励
  • 横幅：以较大的矩形区域展示的详情页插入广告
  • Banner：在APP顶/中/底部悬浮且可关闭的边栏广告
  • 插屏：在弹出窗口上展示的广告
  • 视频贴片：在视频片头片尾或随片播放的广告

• 新广告场景定义：

  • 开屏广告：用户启动或切换回 App 时展示的广告
  • 信息流广告：App 推荐列表（信息流）里展示的广告
  • 激励广告：用户主动体验服务以获取 App 内奖励时展示的广告
  • 详情页插入广告：App 详情页内随内容呈现插入展示的广告
  • 横幅广告：固定在 App 页面内顶/中/底部展示的广告
  • 插屏广告：在 App 自然停顿和切换时弹出展示的广告
  • 视频贴片广告：在视频片头、片尾或随片播放展示的广告

2.2 模块介绍

本节对Media API的各个模块分别做简单介绍，以便对接人员快速了解每个模块的大致功能。
根据接口功能不同，系统可分为媒体模块、广告位模块 、报表模块3类。各模块功能简介如下：

• 媒体模块：媒体创建和媒体信息修改功能；
• 广告位模块：广告位创建和广告位信息修改功能；
• 报表模块：查询一定时间段内不同媒体、不同广告位类型、不同广告位的广告效果数据；

2.3 技术准备

本API文档所涉及接口均遵循HTTP协议。
调用方应根据具体接口的要求设置 HTTP Method为 GET或POST。
您可以使用任何支持HTTP协议和JSON格式的编程语言开发应用程序。

有关标准HTTP协议，可参考 RFC2616 或 维基百科-HTTP 相关介绍。
有关JSON数据格式，可参考 JSON.ORG 或 维基百科–JSON 相关介绍。

3. 对接流程

第1步，开通Media API权限：
    请按以下格式发送邮件到 ADNET@tencent.com 获取授权及密钥：
    邮件主题：Media API开通申请
    邮件内容：开发者名称、会员ID、申请原因
   （我们会在1-2个工作日内核对您的申请，请您后续在优量汇“开发者平台—接入中心—Media API接入—我的密钥”查看您的密钥信息）
第2步，开发对接：对接过程中如果遇到疑问，可联系运营接口人进行相关的产品和技术答疑；
第3步，测试联调：在开发完成，开发者部署好服务器后，优量汇可支持开发者进行测试联调，测试环境使用公共账号和密钥联调；
第4步，正式环境上线：测试联调通过后，向运营接口人申请线上正式环境密钥，并上线。

4. 接口详述

4.1 通用声明

4.1.1 权限认证

Media API 通过授权令牌（TOKEN）进行权限控制。TOKEN需要在每次请求时通过Header中 token 字段来传递，提供测试域名：test-api.adnet.qq.com；测试memberid：608070200058；secret：M#z_:cS7ME.^*;_Abi;r/32n!D}>9JVx。

4.1.2 编码方式

若无特殊说明或响应头中的Content-Type未指定编码，请求和响应中的字符编码均使用 UTF-8（无 BOM 头）。

4.1.3 URL定义

请求URL参考RESTful风格，约定了使用的协议、域名、模块、版本、资源及动作，详细定义如下：
https://api.adnet.qq.com/open/API_VERSION/RESOURCE_NAME/RESOURCE_ACTION
其中：
协议：必须使用HTTPS
API_VERSION：版本号，当前版本号码为 v1
RESOURCE_NAME：表示要操作的资源，如medium、placement
RESOURCE_ACTION：表示对资源的动作，如add、update
RESOURCE_NAME目前支持如下资源：

RESOURCE_ACTION目前支持如下基本动作：

4.1.4 通用参数

以下是每个接口都会用到的通用参数，详细定义为：

通用参数并不在API请求的body中，而是放在请求头传输，例：curl --location --request POST 'https://test-api.adnet.qq.com/open/v1.1/medium/add' --header 'token:cnRiLDE1ODQ0MzU0MTYsN2MwNWFlMjhlNDM1ZGYwOWM5MmY2MjkxMjEwMGM3ZTQ4NmU1MzgxNQ==' token是合作伙伴重要的身份标识，优量汇会对 token的使用进行校验，请妥善保管好优量汇接口人提供的生成token的关键信息和 token生成算法，防止泄露。一旦发现token泄露,请立即联系优量汇接口人报备处理。
token 生成规则如下：
token = base64('memberid','time','sign');
其中：
memberid：账户ID，由开发者在优量汇开发者平台（ https://e.qq.com/dev/index.html ）注册获得；
time：发起请求时的unix时间戳（精确到秒），此值跟接收到请求时的服务器时间戳值偏差（正负）, 超过1200秒（20分钟）时，请求会被忽略，要求调用方重新组合token（请使用 Asia/Shanghai时区）；
sign： 签名字符串，sign = sha1(memberid. secret. time)，secret为约定的私钥, 合作伙伴申请 API接口时，由优量汇提供，sign是在时间戳的基础上进行加密的，当时间戳超过系统设定时间间隔之后，请求会被拒绝，要求调用方重新组合 token,加密算法可采用 sha1。
以上参数中，memberid、secret 这两个参数是优量汇生成token的关键参数，请联系优量汇接口人获取secret。
下面举例说明如何生成token（python2语言为例）。
假设生成 token的各个参数取如下数值：
memberid：12345
secret：032742947398^*
生成token代码：

import hashlib
import base64
import time
memberid="12345"
secret="032742947398^*"
timestamp=int(time.time())  //时间戳，精确到秒
sign = hashlib.sha1( memberid + secret + str(timestamp) ).hexdigest()
list_v = [memberid, str(timestamp), sign]
plain = ','.join(list_v)
token = base64.b64encode(plain)
print token

这样，我们就生成了本次API请求的token了。

4.1.5 API请求

• HTTP Method
  如无特殊说明，add、update API请求的HTTP Method为POST；get API请求的HTTP Method均为GET

• HTTP Header
  调用方应遵循HTTP协议设置相应的Header，目前支持的Header有：Content-Type用于指定数据格式。POST请求数据默认格式为：multipart/form-data ，具体情况请参考接口的详细说明文档。

  HTTP Header示例

    Content-Type: multipart/form-data
  

4.1.6 API响应

• HTTP状态码

支持HTTP标准状态码，具体如下：

其中，4xx 和 5xx 的状态码仅用于辅助调用方快速识别问题，不作为包含实际语义的错误码，若有调整也不另行通知，实际操作结果以API返回的数据为准。调用方也应能够识别和处理由于网络异常等因素导致的，由非API 服务返回的 HTTP 状态码，如 504 Gateway Timeout 等。

• HTTP Header

目前API响应的Content-Type为application/json。

• HTTP Body

响应的JSON数据中包含三部分内容，分别为返回码、返回信息和数据，如下表所示：

4.2 媒体模块

规则说明：

1. 建修改媒体，以app_id作为媒体id的唯一识别；
2. 只有审核通过的媒体才可以修改。

4.2.1 创建媒体

请求URL：https://api.adnet.qq.com/open/v1.1/medium/add

请求方法：POST

Content-Type：multipart/form-data

请求字段：

应答字段：

请求示例：

curl --location --request POST 'https://test-api.adnet.qq.com/open/v1.1/medium/add' \
--header 'token: cnRiLDE1ODQzNzc0MTcsZDVjNjIzNWRkZTY1MTFmMGJmMWQyNzlkMTE0ZjI3M2ZmYzgyMGIxMA==' \
--header 'Content-Type: multipart/form-data' \
--form 'member_id=2763558177' \
--form 'medium_name=腾讯视频' \
--form 'icp_picture=@/Users/Desktop/WechatIMG197.jpeg' \
--fom 'os=1' \
--form 'industry_id_v2=2000402' \
--form 'detail_url=https://android.myapp.com/test' \
--form 'affiliation=Own' \
--form 'soft_right_img_id=1' \
--form 'biz_right_img_id=2'  \
--form 'package_name=com.tencent.live' \
--form 'profit_mode=IAA' \
--form 'full_package_name=com.tencent.live' \
--form 'sha1=89:0C:D5:BC:2C:96:F0:73:D4:8E:8C:BC:CF:D6:0C:66:91:68:66:05'

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "app_id": 1110525172
    }
}

4.2.2 修改媒体

请求URL：https://api.adnet.qq.com/open/v1.1/medium/update

请求方法：POST

Content-Type：multipart/form-data

请求字段：

应答字段：

请求示例：

curl --location --request POST 'https://api.adnet.qq.com/open/v1.1/medium/update' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
--form 'member_id=2763558177' \
--form 'industry_id_v2=2000402' \
--form 'detail_url=https://android.myapp.com/test' \
--form 'package_name=com.tencent.live' \
--form 'full_package_name=com.tencent.live' \
--form 'sha1=89:0C:D5:BC:2C:96:F0:73:D4:8E:8C:BC:CF:D6:0C:66:91:68:66:05' \
--form 'affiliation=Agency' \
--form 'profit_mode=IAA' \
--form 'app_id=1110525172'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.2.3 获取媒体

请求URL：https://api.adnet.qq.com/open/v1.1/medium/list

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

4.3 广告位模块

4.3.1 创建广告位

请求URL：https://api.adnet.qq.com/open/v1.1/placement/add

请求方法：POST

Content-Type：application/json

请求字段：

FilterRule 过滤规则

RtbConfig

*RTB对接时 rtb_relation相关参数哪些为必填项，哪些为非必填项，请参考4.3.4RTB对接时创建广告位细分场景说明

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/add' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id": 2763558177,
    "app_id": 1101152570,
    "placement_name": "test 12",
    "ad_pull_mode": "SDK",
    "scene": "FLOW",
    "rewarded_video_scene": "OTHER",
    "rewarded_video_scene_description": "demoData",
    "placement_image_id": 1,
    "render_type": "NORMAL",
    "ad_crt_type_list": [
        "IMAGE"
    ],
    "ad_crt_normal_type": 1,
    "ad_crt_template_type": [
        "RP_LT"
    ],
    "flash_crt_type": "FLASH",
    "rewarded_video_crt_type": "ALL_DIRECTION",
    "ad_feedback_element": [
        "APP_DL_IMG"
    ],
    "filter_rule": {
        "filter_keywords": [],
        "filter_pkg_names": [],
        "filter_ituns_ids": [],
        "filter_categories": ["P2P_LENDING_PRODUCT"]
    },
    "enable_experiment": true
}'

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "placement_id": 9010062089859016
    }
}

4.3.2 修改广告位

请求URL：https://api.adnet.qq.com/open/v1.1/placement/update

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/update' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id": 2763558177,
    "placement_id":2353536546547235,  
    "placement_name": "demoData",
}'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.3.3 获取广告位

请求URL：https://api.adnet.qq.com/open/v1.1/placement/list

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/list' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id": 2763558177,
    "filtering": [
        {
            "field": "ad_pull_mode",
            "operator": "EQUALS",
            "values": [
                "SDK"
            ]
        },
        {
            "field": "scene",
            "operator": "EQUALS",
            "values": [
                "REWARDED_VIDEO"
            ]
        }
    ],
    "page": 1,
    "page_size": 5
}'

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "list": [
            {
                "placement_id": 103000000,
                "placement_name": "广告位名称",
                "app_id": 110000000,
                "scene": "REWARDED_VIDEO",
                "rewarded_video_scene": "TASK_REWARD",
                "rewarded_video_description": "",
                "ad_pull_mode": "SDK",
                "render_type": "NORMAL",
                "ad_crt_type_list": [
                    "VIDEO"
                ],
                "ad_crt_template_type": null,
                "ad_crt_normal_type": 0,
                "flash_crt_type": "",
                "rewarded_video_crt_type": "ALL_DIRECTION",
                "ad_feedback_element": null,
                "status": "Freeze",
                "pause_status": "Normal",
                "filter_rule": null
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 5,
            "total_number": 1,
            "total_page": 1
        }
    }
}

4.3.4 RTB对接时创建广告位细分场景说明

1). 使用对方协议合作，使用Media API创建广告位：请求中带了开发者广告位id，且和优量汇广告位id可一一对应：

2). 使用对方协议合作，使用Media API创建广告位：请求中没有带开发者广告位id的：

3). 使用优量汇API协议接入，通过Media API管理广告位：

4.3.5 删除广告位

规则说明：

1. 处于自动优化层的广告位不得删除;
2. 非冻结状态广告位不得删除;
3. 资讯广告位不得删除。

请求URL：https://api.adnet.qq.com/open/v1.1/placement/delete

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/delete' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "placement_id":5010159514522894,  
    "member_id":2763558177
}'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.3.6 解冻广告位

规则说明：
解冻广告位状态会实时生效，但解冻后的广告位正常获取到广告存在延迟，最大延迟3小时。

请求URL：https://api.adnet.qq.com/open/v1.1/placement/unfreeze

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/unfreeze' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "placement_id":5010159514522894,  
    "member_id":2763558177
}'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.3.7 暂停广告位

请求URL：https://api.adnet.qq.com/open/v1.1/placement/pause

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/pause' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "placement_id":5010159514522894,  
    "member_id":2763558177
}'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.3.8 启动广告位

请求URL：https://api.adnet.qq.com/open/v1.1/placement/start

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/start' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "placement_id":5010159514522894,  
    "member_id":2763558177
}'

应答示例：

{
    "code": 0,
    "message": "ok"
}

4.4 报表模块

4.4.1 查询报表

测试联调：使用测试账号，请求测试环境，报表接口是mock数据，日期请求20200414。

请求URL：https://api.adnet.qq.com/open/v1.1/report/get?member_id=xxx

请求方法：GET

Content-Type：application/json

支持查询参数

返回参数

ReportResult参数详情

请求示例：

curl --location --request GET 
'https://api.adnet.qq.com/open/v1.1/report/get?member_id=2763558177' \
--header 'token:
cnRiLDE1ODQzMzI3NDQsNzEwZDY3MjNkNWViOWYxNWEwZmFkMTlhNjRiNWU5NWY1MDgwZDU5Mg==' \

应答示例：

{
    "code": 0,
    "message": "ok",
    "data":{
        "list": [{
        "placement_id": 2040498460877118,
        "member_id": 2763558177,
        "app_id": 1101152570,
        "medium_name": "SDK Demo",
        "placement_name": "模板-图文-浮层单图-勿动",
        "date": "2020-06-09",
        "placement_type": "原生",
        "exposure_rate": "8.13%",
        "fill_rate": "75.00%",
        "click_rate": "10.00%",
        "ecpm": "8.50",
        "revenue": "11.05",
        "click": "130",
        "pv": "1300",
        "request_count": "20000",
        "return_count": "15000",
        "ad_request_count": "22000",
        "ad_return_count": "16000",
        "is_summary": false
      }]
    }
}

4.5 图片资源上传

图片类上传，统一先通过该接口上传资源，接口返回资源id之后，通过资源id来标识该图片。

请求URL：https://api.adnet.qq.com/open/v1.1/image/upload

请求方法：POST

Content-Type：multipart/form-data

请求字段：

返回参数

请求示例

curl --location --request POST 'https://adnet.qq.com/open/v1.1/image/upload' \
--header 'token: cnRiLDE1ODQzNzc0MTcsZDVjNjIzNWRkZTY1MTFmMGJmMWQyNzlkMTE0ZjI3M2ZmYzgyMGIxMA==' \
--header 'Content-Type: multipart/form-data' \
--form 'member_id=2763558177' \
--form 'type=PLACEMENT_IMAGE' \
--form 'file=@/Users/Desktop/WechatIMG197.jpeg' \

应答示例

{
    "code": 0,
    "message": "ok",
    "data":{
      "image_id" : 1
       }
 }

4.6 工具模块

4.6.1 获取美元汇率

请求URL：https://api.adnet.qq.com/open/v1.1/resource/get_usd_rate

请求方法：GET

支持查询参数：

返回参数

附录

附录1. 返回码定义

附录2. 行业

附录3. 自渲染广告样式

附录4. 枚举值定义

场景 scene

模板版本生成规则 template_version

激励场景 rewarded_video_scene

接入方式 ad_pull_mode

渲染方式 render_type

素材类型 ad_crt_type

开屏广告样式 flash_crt_type

激励广告样式 rewarded_video_crt_type

模板类型 ad_crt_template_type

过滤行业 filter_categories

价格策略类型 price_strategy_type

广告返回元素 ad_feedback_element

rtb绑定的os rtb_relation_os

上传图片类型type

应用广告跳落地页确认 download_land_page

媒体状态

广告位暂停状态

广告位状态

服务端校验是否开启

媒体测试状态

广告位测试状态

游戏变现类型

广告位开关类状态

附录5. 旧广告场景与广告位类型映射关系

附录6. 不同接入方式场景下支持的广告样式

附录7. 媒体隶属关系

附录8. 价格策略

附录9. 新三级行业

附录10. 广告三级场景点与场景映射关系

附录11. 广告场景默认三级场景点