一、引言
1、目的
使用本文档接口，可方便合作伙伴实时获取广告位报表。
2、使用范围
经小米移动广告联盟（以下简称米盟）授权、可在移动应用上展示小米广告联盟广告产品的联盟伙伴或流量聚合平台（以下简称为“合作伙伴”）。
3、功能概述
合作伙伴通过 HTTP 请求的方式向米盟的 Web Service 请求提供服务，米盟根据合作伙伴提交的信息支持查询不同应用、不同广告位的效果数据的功能。
二、接口功能
1、实时效果数据查询
支持的查询功能如下：
实时（在T+1小时查看T小时的数据）查询一定时间段某一应用下不同广告位的广告效果数据。
2、请求接口
地址：https://dev.mi.com/sspsettle/report/api/hour/data/stat/detail
方式：POST
请求和参数通过 url 请求的方式（POST 请求）传递给小米广告联盟。
2.1、请求参数定义
| 参数名称 | 参数含义 | 参数类型 | 是否必须 | |
| devid | 米盟开发者ID | int64 | 是 | |
| appid | 米盟应用 ID | int64 | 是 | |
| token | 鉴权码 | string | 是 | |
| start_time | 起始时间 | string | 日期格式yyyyMMddHH | 是 |
| end_time | 截至时间 | string | 日期格式yyyyMMddHH，起止日期间隔为7天 | 是 |
2.2、请求url样例
curl -X POST –data 'devid=1174&appid=2882517536307&start_time=2023102300&end_time=2023102323& token=MTE3NCwyODgyNTE3NTM2MzA3LDE2OTg3Mzk2NjEsZTU4MmQzMGY2NjE3ZTc2OWFkNjgwZDM3MjU2ZTg4ZTllOGViMTJmYw==' https://dev.mi.com/sspsettle/report/api/hour/data/stat/detail
3、相应接口
广告数据将采用 JSON 格式返回给合作伙伴，该 JSON 文件米盟端不保存，下面是 JSON 文件的样例和说明。
3.1、响应样例
{
"errorCode": 0,
"reason": "成功",
"details": [
{
"dateTime": "2024060109",
"developerId": 1174,
"publisherId": 2882517536307,
"placementId": "3ae7d86ac17c9bdfdc4ad9e0d62fb09c",
"placementName": "示例广告位名称",
"styleName": "系统开屏",
"request": 12,
"requestSuccess": 11,
"view": 7,
"click": 3,
"startDownload": 2,
"revenue": 0.12,
"ctr": "0.4286",
"fillRate": "0.8333",
"ecpm": "17.1428"
}
]
}注：以上数据仅作为示例，数值均为虚构。
3.2、状态码定义
返回包含3个部分：返回码、返回说明、返回数据。返回码和返回说明是对这次请求是否成功的说明。
返回码的值及对应的含义如下：
| 代码 | 含义 | 解释 |
| 0 | 成功 | 成功 |
| 5 | 开发者不存在 | 开发者id填写错误 |
| 7 | 应用不存在 | 应用id填写错误 |
| 63 | 服务端异常 | 米盟服务器异常 |
| 64 | 参数有误 | 包含日期区间超过限制（7日），token鉴权失败等 |
| 65 | token过期 | token里的时间戳过期，请更换 |
| 66 | 系统繁忙，请稍后再试 | 系统当前负载过高，无法及时处理用户的请求或操作 |
3.3、返回字段
| 字段名称 | 类型 | 描述 |
| dateTime | string | 时间 yyyyMMddHH |
| 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说明
1.1. devid：米盟开发者ID；请登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）右上角账户信息获取。
1.2. appid：米盟应用ID；请登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）【我的应用】菜单获取。
1.3. time：发起请求时的Unix时间戳；当这个值与接收到请求时的服务器时间戳值偏差（±），超过1200秒（20分钟）时，请求会被忽略，请调用方重新组合token（请使用Asia/Shanghai时区）。
1.4. sign：签名字符串；sign=sha1(devid.appid.appSecret.time)，appSecret为约定的私钥，由米盟提供，sign是在时间戳的基础上进行加密的，加密算法可采用sha1。
2、获取 appSecret
appSecret 是生成token的关键参数，获取方式如下：
2.1. 登录米盟广告变现平台（https://dev.mi.com/union/static/index.html）
2.2. 进入【账号信息】菜单
2.3. 在【密钥信息】栏可查看和复制appSecret
请合作伙伴妥善保管，一旦发现泄露，请联系米盟接口人配合应对。
3、生成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。
4、请求限制
目前仅支持某个应用下按广告位粒度的统计数据，暂不支持广告类型维度的查询。 查询时间区间目前设置上限为七天。