腾讯优量汇 Media API 接入文档

Version: 1.1.9

法律声明

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

版本管理

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

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

更新日志

重要知会

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顶/中/底部悬浮且可关闭的边栏广告
  • 插屏：在弹出窗口上展示的广告
  • 视频贴片：在视频片头片尾或随片播放的广告

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权限：开发者向运营接口人提供相关信息（优量汇会员id和账户名称）获得相应的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=50401' \
--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'

应答示例：

{
    "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=50401' \
--form 'detail_url=https://android.myapp.com/test' \
--form 'package_name=com.tencent.live' \
--form 'affiliation=Agency' \
--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_JOINT",
    "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": 1,
    "placement_id":2,  
    "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.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=123' \
--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

激励场景 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. 价格策略