应用分发广告 API 接入文档

当前版本：v2.0.17（已部署）

待发布兼容扩展：下载图文广告的应用明示与广告标识，见 4.7 节。版本号、请求鉴权和现有回调参数保持不变；新增展示能力须按广告位验收后启用。

• 接入准备（含 测试广告位 test-ad）
• 请求字段
• 响应与事件监测
• 状态码
• 开发示例
• 联调验收

修订记录：

1. 文档说明

本文档定义应用分发广告的请求格式、响应字段及事件监测方式。

1.1 平台枚举定义

以下枚举由本平台定义，媒体按此填写和解析。平台对不同广告服务使用统一取值，不会在响应中暴露其他编码；后续新增广告服务也使用同一套取值。

1.1.1 adType 广告类型

1.1.2 interactionType 交互类型

请求固定使用 20；响应为广告实际交互类型，平台原样返回，下载类常见 19、20，兼容值 14、16 也可能出现。

1.1.3 downloadAd / nativeAdType / htmlType

1.1.4 设备与网络

1.1.5 视频

当前平台不投放视频，以上字段仅协议兼容。

1.1.6 eventType

1–20，编号见 4.3 节。

2. 接入准备

2.1 请求地址

POST https://adhit.cn/rtb/bid

开始开发前取得以下配置：

竞价请求由媒体服务端发起；设备字段填写实际用户终端的信息。鉴权 token 不放入客户端或前端代码。

2.2 请求格式

• 请求类型：POST
• 数据格式：JSON，请求头需设置 Content-Type: application/json
• 字符编码：UTF-8；字段名区分大小写
• Gzip 压缩：支持；压缩请求体时设置 Content-Encoding: gzip，不压缩时省略该请求头
• 请求体上限：未压缩请求为 4 MiB；gzip 请求压缩后为 4 MiB，解压后为 2 MiB
• JSON 数字字段传数字，字符串字段传字符串；例如 os: 2、targetTypeStr: "2"
• 可选字段无值时省略；ext 如需填写，传字符串形式的 JSON，例如 "ext": "{\"key\":\"value\"}"
• 广告按实际需求实时请求，不缓存响应供后续请求复用

2.3 请求鉴权

每个请求只需在 URL query 中携带 requestId、auth，无需传接入方 ID。平台根据请求体 imp[].tagId 识别接入方，再用该接入方的 token 校验签名。未开通广告位、停用接入方、签名错误，或一次请求混用不同接入方的广告位时返回 HTTP 401，不调用广告服务：

示例：

POST https://adhit.cn/rtb/bid?requestId=20261012120000000001&auth=<MD5("20261012120000000001"+本媒体token) 转大写>

签名步骤：

1. 生成本次请求的 requestId。
2. 将 requestId 原文与 token 原文直接拼接，不加分隔符、空格或换行；token 按平台下发的字符串原样使用，区分大小写，不做 hex 解码或大小写转换。
3. 对拼接结果的 UTF-8 字节计算 MD5，将十六进制结果转为大写。
4. 将 requestId、auth 作为 URL query 参数发送，JSON 请求体按第 3 节填写。

建议 query 中的 requestId 与请求体的 id 使用同一值；响应 id 回显请求体的 id。签名不包含请求体，token 不在请求中传输，必须使用 HTTPS。

每个 tagId 由平台分配，只能属于一个接入方；一个请求中的所有非空 tagId 必须属于同一接入方。广告位停用后不会转给其他接入方，签名正确但广告位已停用时返回 204。requestId、auth 各只能传一次。监测回调仅使用响应中的完整 URL，每条广告的 token 已绑定接入方身份。

以下仅用于本地核对签名算法，示例 token 不能用于真实接口：

2.4 测试广告位 test-ad

存量接入方保留使用 test-ad，其他接入方由平台分配独立的 test-ad-<接入方ID>，例如 test-ad-m2。测试位需先为接入方开通，不与其他接入方共享；未开通的广告位返回 401，已开通但停用的广告位在签名正确时返回 204。开发阶段可使用分配的测试位验证签名、响应解析和监测回调，再切换正式 tagId。

使用限制：

• 仅用于接口联调，不用于正式放量，不做压测；请低频、少量请求。
• 默认测试广告的回调不转发、不计费；其他广告的回调规则与正式广告位一致。测试广告位的回调都不作为对账或收入核对依据。
• 回调时只请求本次响应中的完整监测 URL，且只在对应事件真实发生时请求（见 4.3 节）。
• 上线前把 tagId 与模板改为商务、产品侧开通的正式配置，并重新验证第 7 节各项。

联调检查项：

3. 广告请求-Bid Request

“必需”表示接入时应提交的字段；条件必需的字段按表内说明填写。无值的设备信号不得编造。

• id 必须非空，device、app 必须为非 null 对象；device.w、device.h、app.version 必须为正值／非空；缺失时返回 HTTP 400。
• imp 缺失或为空时返回 HTTP 204。此时没有 tagId，无法识别接入方，平台只校验 requestId、auth 的格式（各出现一次，requestId 为 1–64 字节，auth 为 32 位十六进制），不校验签名内容；格式不符仍返回 HTTP 401。该请求不调用广告服务。
• timeout 缺省或小于等于 0 时使用 300ms，大于 5000 时按 5000ms 处理。该时间预算由整个请求共享；客户端网络超时应额外留出传输时间。
• 一次请求可包含多个广告位，每个 imp.id 应在本次请求中唯一；各广告位按顺序处理，共享同一 timeout。
• 非空但未开通的 tagId 无法识别接入方，整单返回 401；同一请求中属于不同接入方的 tagId 同样返回 401，不先处理其中的曝光位。
• 签名通过后，缺失 tagId、templateList 为空或广告位已停用的曝光位被跳过；全部跳过或无填充返回 204。若所有曝光位均缺失 tagId，仅保留存量接入方 token 的兼容校验。

3.1 Imp 对象

3.2 Template 对象

模板按列表顺序选择第一个 targetTypeStr 包含 "2" 的条目；如无此条目则选择第一项。请显式填写 "2"，并使用已约定的模板和尺寸。选中模板的 width/height 作为请求尺寸使用，templateId 在响应中回显；templateList 中的其余模板不参与匹配。

3.2.1 Video 对象（请求）

请求视频类广告时在 imp[].video 提供。平台当前不投放视频广告，本节字段为协议兼容保留，不参与召回，媒体无需填写。

3.2.2 CustomizedInfo 对象

3.3 Device 对象

设备标识填写规则：

• 原值和 MD5 至少提供一种；同时提供时须对应同一原值。已有 MD5 不再二次哈希，大小写均可接收，建议统一使用小写。
• Android 同时提供 IMEI 和 OAID 时，IMEI 标识优先；iOS 使用 IDFA 标识。
• did 原值与 MD5 都会使用；只提供其中一种时，由平台补全另一种（MD5 统一转大写）。
• androidId 及 paid～appstoreVersion 反作弊字段仅在有真实值时填写，不得编造；未提供时不下发。
• 未提供可用设备标识会影响广告填充；仅填写 caidList 不能满足当前 iOS 请求的设备标识要求。
• h、w 为物理像素，不填写 CSS 像素或逻辑分辨率。
• hwv、ppi、pxRatio、language 为保留信号，当前不参与广告召回。

3.4 Geo 对象

3.5 App 对象

3.6 CaidBase 对象

4. 广告响应-Bid Response

• HTTP 200：响应体为 JSON，包含 bidList。
• HTTP 204：无广告，响应体为空，不进行 JSON 解析。
• 其他状态：按第 5 节处理，不展示该响应中的广告。

响应处理规则

1. 校验响应 id 与本次请求体的 id 一致。
2. 按 impId 将每条广告关联到请求中的曝光位，使用响应的 templateId 渲染。
3. 同一曝光位可能返回多条广告；未出现的曝光位按无广告处理。广告位之间可能仅有部分返回，单个曝光位返回条数不固定，不超过 reqadnum：推荐位等非洗包场景未填 reqadnum 时返回 1 条，填写后最多 reqadnum 条（上限 8）；洗包按 pkgWhitelist 填充时，未填 reqadnum 的条数等于被覆盖的包数（不超过 100，也不超过列表条数），填写后最多 reqadnum 条；洗包未带 pkgWhitelist 时未填 reqadnum 最多 8 条。
4. 可选字段缺失、监测数组为空时跳过相应操作；解析时允许出现新增字段。
5. Android 下载使用非空的 downloadUrl。缺少下载地址时，只有已有可用下载渠道才展示下载入口，否则跳过该广告。
6. price 按十进制字符串读取，无需解密；不同计价口径的价格不直接比较。
7. 返回顺序：有预算包在前、无预算填充包在后；同一包名在同一曝光位只出现一次，有预算包优先。区分两类广告见 4.1 节 price 与 4.8 节。

4.1 BidBase 对象

以上创意字段无值时一律省略，媒体不得假定其存在；按安装计费的广告（id 以 free- 开头）只含 4.1 前八个字段与 4.2 的 appName/pkgName/iosAppid/iconUrl/downloadUrl。

枚举字段按 1.1 节解析；targetType 恒为 2，adType／interactionType 可能有多个取值，媒体渲染不依赖具体值。

4.2 BidAdContent 对象

调起顺序：deepLink → 失败后 downloadUrl → 最后 landingUrl。universalLink 是 iOS 的另一个调起地址，它与 deepLink 的先后未作规定，iOS 端接入时需联调确认。

4.2.1 Image / Video / MiniProgram / WechatExt 对象

字段缺失时省略；平台不校验素材地址是否可访问。

4.3 TrackBase 对象

track 为对象数组；六个常规事件字段是 URL 数组，eventTracks 是带事件编号的对象数组。事件发生时，遍历所有 track 对象，逐个请求对应事件的全部 URL。

eventTracks 可选；每项包含 eventType（int）和 eventTrackUrls（URL 数组）。事件发生时，只请求同编号项中的全部链接。未返回的编号不请求；禁止把下载、安装或点击当作调起成功。

notice 仅在该广告支持竞败通知时出现（按安装计费的广告没有）。URL 携带 macroVersion=1 与 macro.__bid_lose__（竞败标识）、macro.__lose_reason__（竞败原因）、macro.__type__（通知类型）、macro.__ext__（扩展信息）占位符参数，参数名带 macro. 前缀，规则与 4.6 节其他宏一致：有真实值就替换参数值，没有就保留占位符原文。请求是否产生效果以线下确认为准；它与曝光、点击、安装回调相互独立，不能互相替代，也不触发结算。

计费与结算事件：

点击、下载、安装开始、通用事件、竞败通知均不计费。

当前物料协议未提供视频素材或视频宏参数，媒体不应模拟视频事件；以下编号仅供解析响应时识别。

监测请求规则：

• 使用 HTTP GET，不使用 POST 或 HEAD。每条链接独立请求，无请求体。
• 原样使用响应返回的完整 URL；不要自行拼接路径、替换 token、追加竞价鉴权参数或修改价格。URL 上带有 macro.<宏名> 占位符参数时：有真实端侧值就替换参数值（每个值做一次 URL 编码），没有就保留占位符原文，不要删除参数，见 4.6 节。
• URL 中的 token 是本条广告的监测凭据，与生成竞价签名的鉴权 token 不同。
• 监测不需要额外提供 requestId／auth；曝光价格宏由平台加密后替换，媒体不提交价格或执行价格加密。监测 URL 上的其他宏按 4.6 节的要求级别处理。
• 对未展示或未被用户操作的广告不上报；每条广告的每次真实事件只触发一次。客户端应按本次响应中的广告及监测链接关联事件，不以广告 id 做全局去重。
• track 对象中的事件字段缺失或 URL 数组为空时跳过；下载或安装阶段不能用点击事件代替。

4.4 Track 上报接口公共参数

各上报接口的域名和完整 URL 均以本次竞价响应为准。以曝光上报为例：

GET /rtb/track/impression?token=rtb-0123456789abcdef0123456789abcdef HTTP/1.1
Host: adhit.cn

通用事件缺失、重复或非法 eventType 返回 HTTP 400；宏参数不参与校验。

同一广告的各事件 URL 可能使用同一监测 token，但路径不同；必须使用对应事件的完整 URL。缺失或无法识别的 token 也会返回 HTTP 204，但不会完成对应广告的上报。

4.5 Track 上报代码示例（Python 3）

调用方保存本次响应的广告对象 ad，真实事件发生后调用 report_event(ad, "imp")；点击使用 "clk"，其余事件使用 4.3 节对应字段。成功调起应用后使用 report_event(ad, "eventTracks", 14)。以下函数逐条发送 GET，不自动重试。

from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen


def report_event(ad, event, event_type=None):
    allowed = {"imp", "clk", "del", "finishDle", "install", "finishInstall", "eventTracks"}
    if event not in allowed:
        raise ValueError("未知广告事件")
    if event == "eventTracks" and (type(event_type) is not int or not 1 <= event_type <= 20):
        raise ValueError("通用事件编号须为 1–20")
    statuses = []
    for track in ad.get("track", []):
        if event == "eventTracks":
            urls = [url for item in track.get("eventTracks", [])
                    if item.get("eventType") == event_type
                    for url in item.get("eventTrackUrls", [])]
        else:
            urls = track.get(event, [])
        for url in urls:
            try:
                with urlopen(Request(url, method="GET"), timeout=5) as response:
                    statuses.append(response.status)
            except HTTPError as error:
                statuses.append(error.code)
            except (URLError, TimeoutError):
                statuses.append(None)  # 交付状态不确定，交由调用方记录与处理。
    return statuses

返回值按每条 URL 给出 HTTP 状态码；网络失败为 None，没有该事件链接则返回空列表。HTTP 204 的含义见 4.3 节。

4.6 宏定义与要求级别（v2.0.14）

宏定义由本文档约定，不在响应体中下发；每次响应实际携带哪些宏，以监测 URL 上的 macro.<宏名> 占位符参数为准。

要求级别取自 360 对接文档「宏替换」一节；该节的内嵌表格在 360 的在线文档里可能更新，以其在线版本为准。

上表为一次响应的示例，不代表每次响应都相同；每次响应携带的宏以 URL 上的 macro.<宏名> 参数为准。

「必须」「推荐」是 360 对媒体的要求，平台不强制：缺值不会被拒绝，但上游收到占位符原文或 -999 可能不符合 360 的要求，影响其归因与反作弊，所以必须类宏请尽量提供真实值。

带宏监测 URL 的处理规则（macroVersion=1）：

1. 平台监测 URL 携带 macroVersion=1 和每个客户端宏一个占位符参数，参数名与参数值均为宏原文，例如 ...?token=...&macro.__down_x__=__down_x__&macro.__DOWN_X__=__DOWN_X__。
2. 触发事件时，媒体把有真实端侧值的占位符参数的值替换为该值，并对该值做一次 URL 编码；没有真实值的参数保留占位符原文，不要删除参数；URL 的其余部分（路径、其他参数、macroVersion）原样保留。真实字符串 "0" 是有效值。
3. 平台不校验 macro.* 参数。下列情形一律按「缺值」处理，回调仍按正常回调受理（HTTP 204，计费与转发规则不变）：参数缺失、值为空、重复（含百分号编码别名）、超过 2048 字节、值仍含自己的占位符原文、该监测 URL 未携带的宏。
4. 平台向上游转发时，有真实值的宏解码一次后按原链接所在组件编码替换；缺值的宏：触点坐标（__down_x__、__down_y__、__up_x__、__up_y__ 及大写变体）填 -999，其余保留上游原占位符。宏名严格匹配、区分大小写。同一宏可出现在多个事件中，各事件独立处理；通用事件按 eventType 汇总同编号全部监测链接的宏。
5. 曝光回调首次携带的可用宏值固定为快照；因失败重试的曝光请求可不再携带宏参数，沿用该快照。
6. 物料链接（landingUrl/deepLink）中的宏按原样下发，由客户端在跳转前处理；平台不参与落地页宏替换，也不能从后续点击回调反推。

仍会返回 HTTP 400 的情形： macroVersion 取值不是本协议支持的版本。除此之外宏不参与校验。

v2.0.8 及更早签发的不带宏监测 URL 不受影响，行为与历史版本一致。

宏所在位置： 只有位于单层查询参数值内的宏才会被替换。宏出现在 scheme/host/port、查询参数名、路径、fragment，或在参数值内被二次编码时，平台不做替换也不拒绝，按原样转发。

媒体接入边界：

• 曝光价格由平台加密替换，媒体不提交或修改价格；提交价格宏会被忽略。
• 能提供真实值的宏请提供，坐标与时间按事件发生时的真实值填写，不要把屏幕或请求模板尺寸当作实际点击时广告尺寸，也不要用 tagId、数组下标等替代值伪造数据；不能提供时保留占位符原文即可。
• landingUrl 中的宏未替换，不能假定是可直接使用的落地页链接。
• 竞败通知 track[].notice 同样按本节处理：媒体回传竞败原因等真实值，平台转发给上游；不要把曝光、点击或安装回调当作竞败通知。

在完成真实端侧数据的联合验收前，不把"有填充"验收当作"事件上报、归因和结算全链路"验收，也不自行构造或替换监测 URL 绕过平台。

4.7 下载图文广告兼容扩展（待发布）

本节尚未发布到生产；启用前由对接双方确认对应广告位的明示展示、单次展示和原有回调能力。未完成验收的广告位继续使用原有广告来源。

四个字段只包含 URL，无值时省略。现有 sensitiveUrl、usesPermission、intro、iconUrl 保持原含义。首期仅支持安卓下载图文，不包含视频、激励视频或 iOS。

示例仅展示新增字段，完整响应结构仍以 6.3 节为准：

{
  "bidAdContent": {
    "privacyUrl": "https://assets.example.com/privacy",
    "permissionUrl": "https://assets.example.com/permissions",
    "appIntroductionUrl": "https://assets.example.com/introduction",
    "adLogoUrl": "https://assets.example.com/ad-logo.png"
  }
}

联调须检查四个入口/标识的实际展示、重复曝光回调仅计费一次、再次展示重新请求，以及未升级广告位继续收到原有字段结构；不能仅以 HTTP 200/204 判定通过。

4.8 洗包场景说明（v2.0.15）

适用于洗包广告位。请求字段与平台行为：

区分有预算包与无预算填充包（4.1 节 price）：

平台默认测试广告（见 2.4 节）不属于以上两类，price 与 source 见 2.4 节。

返回规则：

1. 返回条数等于被覆盖的包数，不超过 100，也不超过列表条数；预算方和平台目录都没有的包不返回，平台不保证覆盖全部列表。
2. 顺序：有预算包在前，按价格从高到低；无预算填充包在后，有价目的在前，其余按请求列表的顺序。
3. 同一包名只返回一次，有预算包优先。
4. 两类广告的监测上报方式完全相同：媒体按 4.3 至 4.6 节对每条广告的全部监测 URL 照常上报，不得因 price 为 "0" 跳过任何上报。是否计费或结算由平台决定。

纯目录广告位（v2.0.16）

平台可按接入方需求开通纯目录洗包广告位，tagId 由平台提供。请求与响应的字段、鉴权、监测上报方式与上文一致，不新增字段。

5. 状态码

6. 请求响应示例

6.1 Android 请求示例

将以下内容保存为 bid-request.json。示例设备信号仅用于演示字段格式；真实调用须换成实际用户终端信息，广告位及模板须使用已开通的配置。

{
  "id": "20261012120000000001",
  "imp": [
    {
      "id": "imp-1",
      "tagId": "YOUR_TAG_ID",
      "templateList": [
        {
          "templateId": "YOUR_TEMPLATE_ID",
          "targetTypeStr": "2",
          "width": 258,
          "height": 258
        }
      ],
      "reqadnum": 1
    }
  ],
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 Chrome/120.0.0.0 Mobile Safari/537.36",
    "ip": "203.0.113.10",
    "deviceType": 1,
    "make": "Google",
    "model": "Pixel 8",
    "os": 2,
    "osv": "14",
    "w": 1080,
    "h": 2400,
    "connectionType": 1,
    "oaId": "23E3BA8B-75E7-423D-BF8F-69C72AAF7986"
  },
  "app": {
    "name": "媒体应用名称",
    "bundle": "com.example.media",
    "version": "1.0.0"
  },
  "timeout": 800
}

iOS 请求使用 os: 1、真实 iOS UA／机型／系统版本，并将 oaId 替换为 idfa 或 idfaMd5。是否展示下载入口按 4.2 节处理。

6.2 可运行的签名与请求示例（Python 3）

保存为 bid-client.py，与 bid-request.json 放在同一目录。设置本环境 token 后运行；仅使用标准库。脚本不自动触发监测请求。

export BID_TOKEN='本环境的鉴权 token'
# 测试时设置商务侧提供的完整地址；正式环境可省略。
export BID_URL='https://adhit.cn/rtb/bid'
python3 bid-client.py

import hashlib
import json
import os
import uuid
from decimal import Decimal
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen


def main():
    token = os.environ["BID_TOKEN"]
    endpoint = os.environ.get("BID_URL", "https://adhit.cn/rtb/bid")
    body = json.loads(Path("bid-request.json").read_text(encoding="utf-8"))
    request_id = uuid.uuid4().hex
    body["id"] = request_id
    auth = hashlib.md5((request_id + token).encode("utf-8")).hexdigest().upper()
    url = endpoint + "?" + urlencode({"requestId": request_id, "auth": auth})
    request = Request(
        url,
        data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        # 示例使用 10 秒网络超时，覆盖本次 800ms 预算及传输时间。
        with urlopen(request, timeout=10) as response:
            if response.status == 204:
                print("无广告", request_id)
                return
            result = json.load(response)
    except HTTPError as error:
        print("HTTP 错误", error.code, "requestId=", request_id)
        return
    except (URLError, TimeoutError) as error:
        print("网络错误", type(error).__name__, "requestId=", request_id)
        return
    if result["id"] != request_id:
        raise ValueError("响应 id 与请求不一致")
    for ad in result.get("bidList", []):
        price = Decimal(ad["price"])
        print("广告", ad["impId"], ad["tagId"], ad["id"], "价格", price)
        # 保存该广告的物料和 track，实际事件发生时按 4.3 节请求对应链接。


if __name__ == "__main__":
    main()

6.3 HTTP 200 平台响应示例

以下为请求测试广告位 test-ad（见 2.4 节）得到的平台响应示例。监测 token 已替换为未签发的 rtb-example-not-issued，不能用于实际监测。

该样例的监测 URL 不带宏占位符参数；带宏响应示例见 6.6 节，回传示例见 6.7 节。

本次响应对应的请求参数如下，与 6.1 节通用请求示例独立：

联调设备参数为样例，不代表真实用户流量；正式请求必须填写真实设备信息。test-ad 的使用范围与限制见 2.4 节；签名使用媒体调用本平台的鉴权 token。

{
  "id": "test-ad-check-6df1e79dddf345cebd1f188bec88649e",
  "bidList": [
    {
      "id": "ad-360test-1",
      "price": "618",
      "bidAdContent": {
        "appName": "示例应用",
        "pkgName": "com.example.app",
        "iosAppid": "",
        "iconUrl": "https://assets.example.com/icon.png",
        "downloadUrl": "https://cdn.example.com/download?packageName=com.example.app&appId=100000000",
        "landingUrl": "https://land.example.com/click?packageName=com.example.app&ad_id=100000001&clklpp=__CLICK_LPP__"
      },
      "track": [
        {
          "imp": [
            "https://adhit.cn/rtb/track/impression?token=rtb-example-not-issued"
          ],
          "clk": [
            "https://adhit.cn/rtb/track/click?token=rtb-example-not-issued"
          ],
          "del": [
            "https://adhit.cn/rtb/track/download-start?token=rtb-example-not-issued"
          ],
          "finishDle": [
            "https://adhit.cn/rtb/track/download-finish?token=rtb-example-not-issued"
          ],
          "install": [
            "https://adhit.cn/rtb/track/install-start?token=rtb-example-not-issued"
          ],
          "finishInstall": [
            "https://adhit.cn/rtb/track/install-finish?token=rtb-example-not-issued"
          ],
          "eventTracks": [
            {
              "eventType": 14,
              "eventTrackUrls": [
                "https://adhit.cn/rtb/track/event?token=rtb-example-not-issued&eventType=14"
              ]
            }
          ]
        }
      ],
      "impId": "imp_check",
      "tagId": "test-ad",
      "targetType": 2,
      "templateId": "1"
    }
  ]
}

平台响应按 bidList 解析，响应体即为上文的 id 与 bidList 结构，没有额外的 code / data / groups 外层。示例仅为广告请求结果，不包含曝光等监测回调。

6.4 HTTP 204 响应示例

HTTP/1.1 204 No Content

无 JSON 响应体。400、401、413 等错误也可能无响应体，按状态码处理。

6.5 监测请求示例

在真实事件发生后，将对应 track 数组中的完整 URL 设置为 TRACK_URL 再执行；例如曝光使用 imp 中的 URL。不要使用 6.3 节的示例 token 请求接口。

curl --request GET --max-time 5 --silent --show-error \
  --output /dev/null --write-out 'HTTP %{http_code}\n' "$TRACK_URL"

正常返回 HTTP 204，无需读取响应体。同一事件有多条 URL 时逐条执行。

6.6 HTTP 200 带宏响应示例

以下为请求测试广告位 test-ad（见 2.4 节）得到的带宏平台响应示例。监测 token 已替换为未签发的 rtb-example-not-issued，不能用于实际监测。

要点：曝光（imp）与点击（clk）监测 URL 携带的宏集合不同——imp 携带 18 个宏（小写触点/时间/传感器宏与 {WIN_POS}），clk 携带 26 个宏（另含全部大写变体 __DOWN_X__/__DOWN_Y__/__UP_X__/__UP_Y__/__WIDTH__/__HEIGHT__/__SLD__ 与 __CLICK_LPP__）。macro.<宏名> 参数名区分大小写，参数值为占位符原文，媒体有真实值就替换，没有就保留。

{
  "bidList": [
    {
      "id": "ad-360test-1",
      "price": "618",
      "impId": "imp-1",
      "tagId": "test-ad",
      "bidAdContent": {
        "appName": "示例应用",
        "pkgName": "com.example.app",
        "iconUrl": "https://assets.example.com/icon.png",
        "downloadUrl": "https://cdn.example.com/download?packageName=com.example.app&appId=100000000",
        "deepLink": "",
        "landingUrl": "https://land.example.com/click?packageName=com.example.app&ad_id=100000001&clklpp=__CLICK_LPP__"
      },
      "track": [
        {
          "imp": [
            "https://adhit.cn/rtb/track/impression?token=rtb-example-not-issued&macroVersion=1&macro.%7BWIN_POS%7D=%7BWIN_POS%7D&macro.__density__=__density__&macro.__down_time__=__down_time__&macro.__x_max_acc__=__x_max_acc__&macro.__y_max_acc__=__y_max_acc__&macro.__z_max_acc__=__z_max_acc__&macro.__sld__=__sld__&macro.__down_x__=__down_x__&macro.__down_y__=__down_y__&macro.__up_x__=__up_x__&macro.__up_y__=__up_y__&macro.__turn_time__=__turn_time__&macro.__turn_x__=__turn_x__&macro.__turn_y__=__turn_y__&macro.__turn_z__=__turn_z__&macro.__up_time__=__up_time__&macro.__utc_end_tms__=__utc_end_tms__&macro.__utc_tms__=__utc_tms__"
          ],
          "clk": [
            "https://adhit.cn/rtb/track/click?token=rtb-example-not-issued&macroVersion=1&macro.__density__=__density__&macro.__down_time__=__down_time__&macro.__x_max_acc__=__x_max_acc__&macro.__y_max_acc__=__y_max_acc__&macro.__z_max_acc__=__z_max_acc__&macro.__sld__=__sld__&macro.__down_x__=__down_x__&macro.__down_y__=__down_y__&macro.__up_x__=__up_x__&macro.__up_y__=__up_y__&macro.__turn_time__=__turn_time__&macro.__turn_x__=__turn_x__&macro.__turn_y__=__turn_y__&macro.__turn_z__=__turn_z__&macro.__up_time__=__up_time__&macro.__utc_end_tms__=__utc_end_tms__&macro.__utc_tms__=__utc_tms__&macro.__DOWN_X__=__DOWN_X__&macro.__DOWN_Y__=__DOWN_Y__&macro.__HEIGHT__=__HEIGHT__&macro.__SLD__=__SLD__&macro.__UP_X__=__UP_X__&macro.__UP_Y__=__UP_Y__&macro.__WIDTH__=__WIDTH__&macro.__CLICK_LPP__=__CLICK_LPP__&macro.%7BWIN_POS%7D=%7BWIN_POS%7D"
          ],
          "del": [
            "https://adhit.cn/rtb/track/download-start?token=rtb-example-not-issued"
          ],
          "finishDle": [
            "https://adhit.cn/rtb/track/download-finish?token=rtb-example-not-issued"
          ],
          "install": [
            "https://adhit.cn/rtb/track/install-start?token=rtb-example-not-issued"
          ],
          "finishInstall": [
            "https://adhit.cn/rtb/track/install-finish?token=rtb-example-not-issued"
          ],
          "eventTracks": [
            {
              "eventType": 14,
              "eventTrackUrls": [
                "https://adhit.cn/rtb/track/event?token=rtb-example-not-issued&eventType=14"
              ]
            }
          ]
        }
      ]
    }
  ]
}

上例仅保留与宏相关的字段，不是完整响应：实际响应的每条广告恒含 id、bidAdContent.iosAppid、targetType、templateId，空的 deepLink 会被省略而不是返回空串；完整字段形态以 6.3 节为准。

6.7 带宏回传示例

回传示例（宏值为演示值，非真实端侧数据）：

曝光回传（有真实值的宏替换，没有的保留原文，平台受理 HTTP 204）：

curl --request GET --max-time 5 --silent --show-error \
  --output /dev/null --write-out 'HTTP %{http_code}\n' \
  "https://adhit.cn/rtb/track/impression?token=<当次响应中的token>&macroVersion=1&macro.%7BWIN_POS%7D=%7BWIN_POS%7D&macro.__density__=3&macro.__down_time__=1791959414599&macro.__down_x__=528.5&macro.__down_y__=<演示值>&macro.__up_time__=1791959414599&macro.__up_x__=<演示值>&macro.__up_y__=761.5&macro.__x_max_acc__=__x_max_acc__&..."

示例里 {WIN_POS}、__x_max_acc__ 没有真实值，保留了原文；__down_x__ 等有真实值，已替换。

缺值回传（全部保留占位符原文，平台同样受理 HTTP 204）：

curl --request GET --max-time 5 --silent --show-error \
  --output /dev/null --write-out 'HTTP %{http_code}\n' \
  "https://adhit.cn/rtb/track/impression?token=<当次响应中的token>&macroVersion=1&macro.%7BWIN_POS%7D=%7BWIN_POS%7D&macro.__density__=__density__&..."

平台不因缺值返回 400；转发上游时，触点坐标填 -999，其余保留上游原占位符。毫秒/秒级时间戳、小数坐标、dpi 密度、超界值、Unicode 等宏值形态均可传输，宏值单位以 360 文档为准。

6.8 洗包响应示例（有预算包与无预算填充包）

请求洗包广告位，imp[0].pkgWhitelist 为 com.example.paid,com.example.fill。以下为响应片段（省略部分可选字段）：第一条为有预算包（price 为 CPM），第二条为无预算填充包（price 为 "0"）。监测 token 已替换为未签发的 rtb-example-not-issued，不能用于实际监测。

{
  "id": "wash-check-001",
  "bidList": [
    {
      "id": "ad-360-1",
      "price": "618",
      "impId": "imp-1",
      "tagId": "wash-tag",
      "targetType": 2,
      "templateId": "1",
      "bidAdContent": {
        "appName": "示例应用 A",
        "pkgName": "com.example.paid",
        "iconUrl": "https://assets.example.com/paid-icon.png",
        "downloadUrl": "https://cdn.example.com/download?packageName=com.example.paid"
      },
      "track": [
        {
          "imp": ["https://adhit.cn/rtb/track/impression?token=rtb-example-not-issued"],
          "clk": ["https://adhit.cn/rtb/track/click?token=rtb-example-not-issued"],
          "finishInstall": ["https://adhit.cn/rtb/track/install-finish?token=rtb-example-not-issued"]
        }
      ]
    },
    {
      "id": "free-com.example.fill",
      "price": "0",
      "impId": "imp-1",
      "tagId": "wash-tag",
      "targetType": 2,
      "templateId": "1",
      "bidAdContent": {
        "appName": "示例应用 B",
        "pkgName": "com.example.fill",
        "iconUrl": "https://assets.example.com/fill-icon.png",
        "downloadUrl": "https://cdn.example.com/download?packageName=com.example.fill"
      },
      "track": [
        {
          "imp": ["https://adhit.cn/rtb/track/impression?token=rtb-example-not-issued"],
          "clk": ["https://adhit.cn/rtb/track/click?token=rtb-example-not-issued"],
          "finishInstall": ["https://adhit.cn/rtb/track/install-finish?token=rtb-example-not-issued"]
        }
      ]
    }
  ]
}

两条广告的上报方式相同；有预算包的 price 为 CPM，无预算填充包的 price 恒为 "0"，据此区分。

7. 联调验收

联调失败时提供请求体 id、query requestId、请求时间、tagId、HTTP 状态码及脱敏请求体；不提供鉴权 token。