腾讯优量汇 Media API 接入文档

Version: 1.1.46

法律声明

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

版本管理

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

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

更新日志

重要知会

1.1.33版本变更关键点

• 开屏将开屏广告样式更新为图片、5秒视频，开屏V+更新为5～30秒长视频+首屏续播、图片、5秒视频并支持修改。
• 激励广告、插屏全屏、横幅广告/信息流/详情页/贴片/沉浸式视频流自渲染支持修改。

1.1.31版本变更关键点

• 增加物理广告位管理相关接口，具体参见接口详述物理广告位模块。
• 广告位创建或修改时支持设置物理广告位，广告位查询接口响应字段增加物理广告位id。

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 'package_name_wx_appid_rel="{\"com.xx.xx\":\"wx9b1xxx3449f\",\"com.xx.xx.xx\":\"wx9b1xxx3xxx9x\"}"' \
--form 'full_package_name=com.tencent.live' \
--form 'media_download_number=1234' \
--form 'media_added_time=20230301' \
--form 'media_account_name=testName' \
--form 'media_rate_number=4561' \
--form 'media_store_score=4.8' \
--form 'media_pull_mode=SDK' \
--form 'is_quick_app=false'

应答示例：

{
    "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 'package_name_wx_appid_rel="{\"com.xx.xx\":\"wx9b1xxx3449f\",\"com.xx.xx.xx\":\"wx9b1xxx3xxx9x\"}"' \
--form 'full_package_name=com.tencent.live' \
--form 'affiliation=Agency' \
--form 'app_id=1110525172' \
--form 'media_download_number=1234' \
--form 'media_added_time=20230301' \
--form 'media_account_name=testName' \
--form 'media_rate_number=4561' \
--form 'media_store_score=4.8' \
--form 'media_pull_mode=SDK' \
--form 'is_quick_app=false'

应答示例：

{
    "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",
                "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": "",
                "media_download_number": 1234,
                "media_added_time": "20230301",
                "media_account_name": "testName",
                "media_rate_number": 4561,
                "media_store_score": "4.3",
                "media_pull_mode": "SDK",
                "is_quick_app": false
            }
        ],
        "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/get

请求方法：GET

Content-Type：application/json

请求字段：

请求示例：

curl -X GET 'https://api.adnet.qq.com/open/v1.1/medium/get' -H 'token: {TOKEN}' -H 'Content-Type: application/json' -d '{"member_id":12345,"app_id":123}'

应答字段：

应答示例：

{
    "code":0,
    "data":{
        "member_id":123456,
        "app_id":12345,
        "medium_name":"",
        "industry_id":10,
        "industry_id_v2":7,
        "os":"1",
        "detail_url":"https://appgallery.huawei.com/app/123456",
        "affiliation":"Own",
        "package_name":"com.qq.aaa",
        "wechat_app_id":"",
        "wechat_universal_link":"",
        "domain":"",
        "icp":"",
        "icp_picture_img_id":0,
        "icp_picture_img_status":"",
        "soft_right_img_id":0,
        "soft_right_img_status":"",
        "company_ship_img_id":0,
        "company_ship_img_status":"",
        "biz_right_img_id":0,
        "biz_right_img_status":"",
        "game_isbn_img_id":0,
        "game_isbn_img_status":"",
        "brand_img_id":0,
        "brand_img_status":"",
        "publisher_agree_img_id":0,
        "publisher_agree_img_status":"",
        "app_market_img_id":0,
        "app_market_img_status":"",
        "ad_cooperation_img_id":0,
        "ad_cooperation_img_status":"",
        "play_mod_setup_img_id":0,
        "play_mod_setup_img_status":"",
        "play_mod_cover_img_id":0,
        "play_mod_cover_img_status":"",
        "play_mod_detail_img_id":0,
        "play_mod_detail_img_status":"",
        "market_icp":"",
        "market_icp_img_id":0,
        "market_icp_img_status":"",
        "market_company_ship_img_id":0,
        "market_company_ship_img_status":"",
        "market_biz_right_img_id":0,
        "market_biz_right_img_status":"",
        "play_mod_desc":"",
        "apk_file_name":"",
        "review_status":"Approved",
        "medium_test_status":"Formal",
        "filter_rule_id":40,
        "package_name_wx_appid_rel":"",
        "media_download_number":0,
        "media_added_time":"",
        "media_account_name":"",
        "media_rate_number":0,
        "media_store_score":"",
        "media_pull_mode":"",
        "is_quick_app":false
    },
    "message":"success"
}

4.2.5 删除媒体

请求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.2.6 彻底删除媒体

规则说明：

1. 最近30天无消耗的媒体可以彻底删除。封禁、违规暂停的媒体不可删除。
2. 删除后媒体下的符合彻底删除规则的广告位也会彻底删除。

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

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl --location --request POST 'https://api.adnet.qq.com/open/v1.1/medium/complete_delete' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "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

CustomRewardContent 自定义奖励信息

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

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

应答字段：

请求示例：

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.3.9 彻底删除广告位

规则说明：

1. 广告位当前状态是冻结或者已删除（调用过4.3.4 删除广告位接口）并且7天无消耗的广告位可以彻底删除。封禁、违规暂停的广告位不可删除。
2. 删除后RTB广告位关联关系同步删除。
3. 删除后广告位与绑定的流量包自动解绑。

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

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

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

应答示例：

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

4.3.10 获取RTB双方广告位映射关系

规则说明：

1. 只有RTB会员才可以使用接口查询数据;

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

请求方法：POST

Content-Type：application/json

请求字段：

应答字段：

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/placement/get_rtb_placement' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "member_id": 2763558177,
    "pos_adx_id_list": [
        "abc","bcd","def"
    ],
    "page": 1,
    "page_size": 3
}'

应答示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "list": [
            {
                "member_id": 12345,
                "adx_id": 22,
                "pos_adx_id": "103000000xxx",
                "placement_id": 103000000
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 3,
            "total_number": 1,
            "total_page": 1
        }
    }
}

4.4 报表模块

4.4.1 查询天级报表

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

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

请求方法：GET

支持查询参数：

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

返回参数

ReportResult参数详情

请求示例：

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

应答示例：

{
    "code": 0,
    "message": "ok",
    "data":{
        "list": [{
        "placement_id": 2040498460877118,
        "member_id": 2763558177,
        "os_platform": "Android",
        "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,
        "cpr": 0.33
      }],
      "page_info": {
            "page": 2,
            "page_size": 100,
            "total_number": 300,
            "total_page": 3
        }
    }
}

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.4.3 查询RTB流量诊断报表

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

请求方法：POST

Content-Type：application/json

请求参数：

返回参数

请求示例：

curl 'https://api.adnet.qq.com/open/v1.1/report/rtb_diagnose' \
--header 'token: cnRiLDE1ODQyODMzMzgsODUzODhjZTcxMmJmYWZlNmI5NzlmOTNkZGE3Mzk1NTFhZTRhMDc2Ng==' \
--header 'Content-Type: application/json' \
-d '{
    "start_date":"20230301",
    "end_date":"20230310",
    "group_by":[
        "adx_id",
        "pos_adx_id",
        "stats_date",
        "package_name",
        "error_code"
    ],
    "order_by":{
        "sort_field":"pos_adx_id",
        "sort_type":"DESC"
    },
    "filtering":[
        {
            "field":"pos_adx_id",
            "operator":"IN",
            "values":[
                "1",
                "2"
            ]
        },
        {
            "field":"package_name",
            "operator":"IN",
            "values":[
                "com.xx.xstore"
            ]
        },
        {
            "field":"error_code",
            "operator":"IN",
            "values":[
                "100133"
            ]
        }
    ],
    "page":1,
    "page_size":10
}'

应答示例：

{
    "code":0,
    "data":{
        "page_info":{
            "total_number":799,
            "total_page":80,
            "page":1,
            "page_size":10
        },
        "list":[
            {
                "stats_date":"20230307",
                "error_msg":"kNoNeedToAccessMixerService",
                "pos_adx_id":"123",
                "adx_id":12,
                "error_code":109502,
                "package_name":"com.xx.xstore",
                "request_count":581890
            }
        ]
    },
    "message":"success"
}

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://api.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. 广告二级、三级场景点与场景映射关系