腾讯优量汇 Media API 接入文档

Version: 1.1.30

法律声明

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

版本管理

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

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

更新日志

重要知会

1.1.30版本变更关键点

• 新增小时级数据查询接口，接口支持获取当天和最近7天共8天的小时级数据，每次查询时可查一天的小时级数据，指标包括预估收入、曝光、千次展示收入、点击量、点击率，具体参见接口4.4.2。
• 只有过去7天bidding收入占比不少于30%的开发者，才有使用该接口的权限。

1.1.28版本变更关键点

• 设置实时竞价广告位不再受收入门槛限制。
• 为帮助开发者提升和监控实时竞价（bidding）变现效果，Media API增加相关指标，包括：竞胜回传量、竞败回传量、竞价结果回传量、广告及广告位竞价结果回传率、竞胜率、竞胜曝光率，详细数据口径与合理值参考区间可见Media API报表接口相关字段。
• 如您发现上述指标异常，可前往优量汇官网帮助中心查看常见问题与诊断排查指引。

1.1.25版本变更关键点

• 为细化请求链路展示，帮助您变现调优，平台升级了下列指标口径：广告位请求量、广告请求量、广告位填充率、广告填充率。
• 本次更新不会变更收入相关数据。

1.1.24版本变更关键点

• 新增数据保护协议签署状态的校验（2022年4月5日开始）。为了共同营造更健康透明的广告生态，确保广告合规和个人信息保护工作有效落地, 请您尽快访问开发者平台完成《数据保护协议》的线上签署, 以免影响您在Media API和开发者平台的正常使用。

1.1.22版本变更关键点

• 新增支持实时竞价配置。设置前须满足：签署实时竞价协议（请到开发者平台签署）&收入满足竞价广告位配置条件。同媒体下支持设置的实时竞价广告位有数量上限。
• 价格策略类型的枚举值新增实时竞价，详见附录8. 价格策略。创建或更新广告位时，如果价格策略类型设置为实时竞价，则必须填写 实时竞价类型。
• 对于实时竞价广告位，解冻时如果同媒体下实时竞价广告位数目已达到上限，则无法解冻。

1.1.20版本变更关键点

• 新增二级广告场景沉浸式视频流 附录10. 广告三级场景点与场景映射关系；
• 插屏广告-优量汇渲染-模板2.0，半屏新增支持弹窗比例1:1 模板类型 ad_crt_template_type；
• 开发者自渲染，5个场景支持素材类型&素材规格的扩充 附录3.1 自渲染广告样式规格；

1.1.18版本变更关键点

• 新增合规承诺函签署状态的校验（2021年12月15日开始）。为了共同营造更健康透明的广告生态，确保广告合规和个人信息保护工作有效落地, 请您尽快访问开发者平台完成《合规承诺函》的线上签署, 以免影响您在Media API和开发者平台的正常使用。

1.1.15版本变更关键点

• 7个广告场景下细分三级场景点 附录10. 广告三级场景点与场景映射关系；
• 创建广告位时可以使用场景（scene）或者三级场景点（custom_position_scene_level3）设置广告位场景，场景参数必须二选一；使用场景时会默认填写三级场景点，默认值映射广告场景默认三级场景点。
• 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）和移动网站；

• 旧广告场景（scene）定义：

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

• 新广告场景（custom_position_scene）定义：

  • 开屏广告：用户启动或切换回 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. 只有审核通过的媒体才可以修改
3. 每个开发者最多可创建300个正式媒体

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 '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 '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

请求字段：

应答字段：

应答示例：

{
    "code": 0,
    "message": "",
    "data": {
        "list": [
            {
                "app_id": 0,
                "medium_name": "abcdef",
                "industry_id": 0,
                "industry_id_v2": 0,
                "os": 0,
                "detail_url": "abcdef",
                "sha1": "abcdef",
                "affiliation": "Unknown",
                "package_name": "abcdef",
                "full_package_name": "abcdef",
                "wechat_app_id": "abcdef",
                "wechat_universal_link": "abcdef",
                "domain": "abcdef",
                "icp": "abcdef",
                "soft_right_img_id": 0,
                "company_ship_img_id": 0,
                "biz_right_img_id": 0,
                "game_isbn_img_id": 0,
                "status": "NotSubmitted",
                "medium_test_status": "Formal",
                "reject_reason": ""
            }
        ],
        "page_info": {
            "page": 0,
            "page_size": 0,
            "total_number": 0,
            "total_page": 0
        }
    }
}

4.2.4 删除媒体

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

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl --location --request POST 'https://api.adnet.qq.com/open/v1.1/medium/delete' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id":2763558177,
    "app_id":1204567
}'

应答示例：

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

4.3 广告位模块

规则说明：

1. 每个媒体最多可创建250个广告位，开发者可通过冻结、删除接口释放限额

4.3.1 创建广告位

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

请求方法：POST

Content-Type：application/json

请求字段：

FilterRule 过滤规则(已废弃)

RtbConfig

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

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

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

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

应答字段：

请求示例：

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_types": ["16_9_image"],
    "ad_crt_template_type": [
        "RP_LT"
    ],
    "flash_crt_type": "FLASH",
    "rewarded_video_crt_type": "ALL_DIRECTION",
    "ad_feedback_element": [
        "APP_DL_IMG"
    ],
    "is_mediation": false,
    "enable_experiment": true,
    "reject_reason":"详情页地址无效，请填写可选应用市场的有效链接",//审核拒绝时有效
}'

应答示例：

{
    "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

请求字段：

应答字段：

| page_info| struct| 分页配置信息|
| - page| int32 | 查询页码 |
| - page_size| int32 | 每页显示的数据条数 |
| - total_number| int32 | 总条数 |
| - total_page| int32 | 总页数 |

请求示例：

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_types": ["16_9_image"],
                "flash_crt_type": "",
                "rewarded_video_crt_type": "ALL_DIRECTION",
                "ad_feedback_element": null,
                "status": "Freeze",
                "pause_status": "Normal",
                "filter_rule": null,
                "is_open_rewarded": "Close",
                "is_mediation": false
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 5,
            "total_number": 1,
            "total_page": 1
        }
    }
}

4.3.4 删除广告位

规则说明：

1. 处于自动优化层的广告位不得删除;
2. 资讯广告位不得删除。

请求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 '{
    "member_id":2763558177,
    "placement_id":5010159514522894
}'

应答示例：

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

4.3.5 解冻广告位

规则说明：
解冻广告位状态会实时生效，但解冻后的广告位正常获取到广告存在延迟，最大延迟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 '{
    "member_id":2763558177,
    "placement_id":5010159514522894
}'

应答示例：

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

4.3.6 暂停广告位

请求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 '{
    "member_id":2763558177,
    "placement_id":5010159514522894
}'

应答示例：

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

4.3.7 启动广告位

请求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 '{
    "member_id":2763558177,
    "placement_id":5010159514522894
}'

应答示例：

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

4.3.8 冻结广告位

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

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

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

应答示例：

{
    "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

支持查询参数：

• 目前已支持广告场景2级数据查询，广告位类型字段会逐步废弃，请开发者尽快更新

返回参数

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.4.2 查询小时级报表

请求URL：https://api.adnet.qq.com/open/v1.1/report/hourly

请求方法：POST

Content-Type：application/json

请求参数：

返回参数

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/report/hourly' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id": 2763558177,
    "date": "20220608",
    "filtering": [
        {
            "field": "custom_position_scene_level2",
            "operator": "IN",
            "values": [
                "FLOW_NORMAL"
            ]
        },
        {
            "field": "app_id",
            "operator": "IN",
            "values": [
                "123456"
            ]
        }
    ],
    "order_by": {
        "sort_field": "ecpm",
        "sort_type": "DESC"
    },
    "group_by": ["app_id", "placement_id"],
    "page": 1,
    "page_size": 5
}'

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "list": [
            {
                "date": "2022-05-20",
                "app_id": 1101152570,
                "medium_name": "SDK Demo",
                "placement_id": 2040498460877118,
                "custom_position_scene_level2": "FLOW_NORMAL",
                "custom_position_scene_level2_name": "常规信息流",
                "revenue": "11.05",
                "revenue": "11.05",
                "ecpm": "8.50",
                "pv": "1300",
                "click": "130",
                "click_rate": "10.00%"
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 5,
            "total_number": 1,
            "total_page": 1
        }
    }
}

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

支持查询参数：

返回参数

4.7 用户洞察模块

4.7.1 上报用户信息

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

请求方法：POST

请求字段：

应答字段：

应答示例：

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

4.7.2 拉取统计数据

请求URL：https://api.adnet.qq.com/open/v1.1/insight/get_stats

请求方法：POST

请求字段：

应答字段：

应答示例：

{
    "code": 0,
    "data": {
        "stats": [
            {
                "data_time": "20210606",
                "active_time": "20210531",
                "product_id": 1738912999,
                "product_name": "",
                "app_id": 1293721361999,
                "main_channel": 1,
                "sub_channel": "wx",
                "os": "",
                "req": 0,
                "fill": 0,
                "fill_rate": 0,
                "pv": 0,
                "pv_rate": 0,
                "uv": 3,
                "click": 0,
                "click_rate": 0,
                "cost": 0,
                "cpm": 0,
                "cpc": 0
            }
        ]
    },
    "message": "success"
}

4.8 对账上报

4.8.1 上报用户信息

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

请求方法：POST

请求字段：

应答字段：

应答字段：

请求示例

{
    "bill_date": "20210805",
    "bill_list": [{
        "placement_id": 4071350381338615,
        "pv": 100,
        "cost": 1000000
    },{
        "placement_id": 4071360393007734,
        "pv": 200,
        "cost": 1500000
    }]
}

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
      "error_list":[
        "placement_id": 873498372489,
        "error_msg": "错误信息"
      ]
    }
}

附录

附录1. 返回码定义

附录2. 行业

附录3. 自渲染广告样式

附录3.1 自渲染广告样式规格

附录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

媒体状态

广告位暂停状态

广告位状态

服务端校验是否开启

媒体测试状态

用户Id类型 user_id_type

广告位测试状态

广告位开关类状态

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

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

附录7. 媒体隶属关系

附录8. 价格策略

附录9. 新三级行业

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

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

附录12. 二级场景点

附录13. 实时竞价类型

附录9. 用户洞察主渠道