修订记录
| 文档版本 | 修订日期 | 修订说明 |
| V1.0 | 2017.3.8 | 文档创建 |
| V1.1 | 2017.3.14 | 完善 token 生成方式 |
| V1.2 | 2017.7.27 | 请求域名地址更改 |
| V1.3 | 2017.10.11 | 完善状态码 |
| V1.4 | 2020.04.05 | 修正请求 url 样例 |
| V1.5 | 2023.07.06 | 更新appSecret获取方式 |
| V1.6 | 2023.08.07 | 返回字段增加广告位名称、广告位类型 |
| V1.7 | 2024.2.27 | 请求url样例中增加linux系统请求样例 |
一、引言
1、目的
使用本文档接口，可方便合作伙伴获取广告位报表。
2、使用范围
经小米移动广告联盟（以下简称米盟）授权、可在移动应用上展示小米广告联盟广告产品的联盟伙伴或流量聚合平台（以下简称为“合作伙伴”）。
3、功能概述
合作伙伴通过 HTTP 请求的方式向米盟的 Web Service 请求提供服务，米盟根据合作伙 伴提交的信息支持查询不同应用、不同广告位的效果数据的功能。
二、接口功能
1、效果数据查询
支持的查询功能如下：
查询一定时间段某一应用下不同广告位的广告效果数据。
1.1 请求接口
地址：https://dev.mi.com/admob/cgi/api/report/get
方式：POST
请求和参数通过 url 请求的方式（POST 请求）传递给小米广告联盟。
1.1.1 请求参数定义
下表是该 POST 请求所 需字段的详细定义和说明。
| 参数名称 | 参数含义 | 参数类型 | 限制 | 是否必须 |
| devid | 米盟开发者ID | int64 | 米盟平台账号 | 是 |
| appid | 米盟应用 ID | int64 | 开发者已创建的app | 是 |
| start_date | 起始日期 | date | 日期格式yyyyMMdd | 是 |
| end_date | 截止日期 | date | 日期格式yyyyMMdd， 如需查询单天，开始和截止日期设置为相同参数即可。起止日期间隔不能过长，目前上限为一个月 | 是 |
| token | 鉴权码 | string | 需要开发者根据<章节3.接口规范>拼装而成 | 是 |
1.1.2 请求url 样例
window系统请求样例
curl -X POST –data 'devid=1174&appid=2882517536307&start_date=20170308&end_date=20170308&token=MTE3NzI0LDI4ODIzMDM3NjE1MTc1MzYzMDcsMTQ4ODk1NTI2MCw5NmU5Mzk4YTYwNzBhYWZiODg5OTc1ZmJiNTZmNTZiNTA0NDk2Zjk2'
'https://dev.mi.com/admob/cgi/api/report/get'linux系统请求样例
curl -X POST --data 'devid=1174&appid=2882517536307&start_date=20170308&end_date=20170308&token=MTE3NzI0LDI4ODIzMDM3NjE1MTc1MzYzMDcsMTQ4ODk1NTI2MCw5NmU5Mzk4YTYwNzBhYWZiODg5OTc1ZmJiNTZmNTZiNTA0NDk2Zjk2' 'https://dev.mi.com/admob/cgi/api/report/get'1.2 响应接口
广告数据将采用 JSON 格式返回给合作伙伴，该 JSON 文件米盟端不保存，下面是 JSON 文件的样例和说明。
1.2.1 响应样例
{
"errorCode": 0,
"reason": "成功",
"details": [
{
"date": "20230601",
"developerId": 1174,
"publisherId": 2882303761517583737,
"placementId": "3ae7d86ac17c9bdfdc4ad9e0d62fb09c",
"placementName": "示例广告位名称",
"styleName": "系统开屏",
"request": 12,
"requestSuccess": 10,
"view": 7,
"click": 3,
"startDownload": 2,
"revenue": 0.12,
"ctr": "0.4286",
"fillRate": "0.8333",
"ecpm": "17.1428"
}
]
}注：以上数据仅作为示例，数值均为虚构。
1.2.2 状态码定义
返回包含3个部分：返回码、返回说明、返回数据。返回码和返回说明是对这次请求是否成功的说明。
返回码的值及对应的含义如下：
| 代码 | 含义 | 解释 |
| 0 | 成功 | 成功 |
| 5 | 开发者不存在 | 开发者id填写错误 |
| 7 | 应用不存在 | 应用id填写错误 |
| 63 | 服务端异常 | 米盟服务器异常 |
| 64 | 参数有误 | 包含日期区间超过限制（一个月），token鉴权失败等 |
| 65 | token过期 | token里的时间戳过期，请更换 |
1.2.3 返回字段
| 字段名称 | 类型 | 描述 |
| date | date | 日期 |
| developerId | int64 | 开发者 id |
| publisherId | int64 | 应用 id |
| placementId | string | 广告位 id |
| placementName | string | 广告位名称 |
| styleName | string | 广告类型 |
| request | int64 | 请求数 |
| requestSuccess | int64 | 填充数 |
| view | int64 | 曝光数 |
| click | int64 | 点击数 |
| startDownload | int64 | 开始下载数 |
| revenue | float | 收入，单位：元 |
| ctr | float | 点击率 |
| eCpm | float | ecpm |
| fillRate | float | 填充率：填充数/请求数 |
三、接口规范
1、token说明
- devid：米盟开发者ID；请登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）右上角账户信息获取。
- appid：米盟应用ID；请登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）【我的应用】菜单获取。
- time：发起请求时的Unix时间戳；当这个值与接收到请求时的服务器时间戳值偏差（±），超过1200秒（20分钟）时，请求会被忽略，请调用方重新组合token（请使用Asia/Shanghai时区）。
- sign：签名字符串；sign=sha1(devid.appid. appSecret. time)，appSecret为约定的私钥，由米盟提供，sign是在时间戳的基础上进行加密的，加密算法可采用sha1。
1.1 获取 appSecret
appSecret 是生成token的关键参数，获取方式如下：
1. 登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）
2. 进入【账号信息】菜单
3. 在【密钥信息】栏可查看和复制appSecret
请合作伙伴妥善保管，一旦发现泄露，请联系米盟接口人配合应对。
1.2 生成token
以下举例说明如何生成 token（伪代码）： 假设生成 token 的各个参数取如下数值 devid: 224657
appid: 2882303761517477589
appSecret: 146295387e4f15e100d27863674c96e6720b62 time：1489398615（时间戳，精确到秒）
经 2 步可以生成 token：
step 1:生成 sign ；
sign = sha1(devid.appid . appkey . time)
=sha1("2246572882303761517477589146295387e4f15e100d27863674c96e6720b621489398615")
= 63838494bb814c17ad752ec3e1546fbc6a24eb1a
step 2:生成 token；
token = base64(devid .','. appid .','. time .','. sign)
=base64(“224657,2882303761517477589,1489398615,63838494bb814c17ad752ec3e1546fbc6a24eb1a")
=MjI0NjU3LDI4ODIzMDM3NjE1MTc0Nzc1ODksMTQ4OTM5ODYxNSw2MzgzODQ5NGJiODE0YzE3YWQ3NTJlYzNlMTU0NmZiYzZhMjRlYjFh
这样，我们生成了本次 api 请求的 token。
2、请求限制
目前仅支持某个应用下按广告位粒度的统计数据，暂不支持广告类型维度的查询。 查询时间区间目前设置上限为一个月。