RTA 实时决策对接指南

RTA Integration Guide

RTA 实时决策对接指南

RTA（Real-Time API）让广告主在竞价瞬间完成流量过滤：元气智广在每次广告请求时实时询问您的参竞意向， 由您基于人群与策略返回参竞计划。本指南覆盖从接口开发到上线的完整流程。

适用对象 · 自建 RTA 服务的广告主 / DSP 对接方式 · HTTP POST + JSON 响应时长 · 60ms 内返回
🏗️
您将构建什么

一个高并发、低延迟的 HTTPS 查询接口：接收元气智广发来的设备信息与候选计划列表（rtaIds）， 查询您的人群与策略数据，60ms 内返回允许参竞的计划列表。 整个对接通常可在 1–2 周内完成（含压测）。

工作原理

RTA 的核心是竞价前置过滤：广告请求到达元气智广后，元气智广不会直接投放， 而是先实时调用您的 RTA 接口，把本次请求对应的候选计划（rtaIds）和用户设备信息发给您； 您根据自己的定向策略筛选出允许参竞的计划返回，元气智广据此决定本次流量是否投放您的广告。

⚡
一次竞价请求的时序
  1. 广告请求到达元气智广 携带候选计划 ID 列表（rtaIds，由您的 RTA 服务分配，用于区分调用的 DMP 库）与用户设备信息。
  2. 元气智广实时调用您的 RTA 接口 以 HTTP POST + JSON 将设备信息与 rtaIds 发给您，要求 60ms 内返回结果。
  3. 您返回参竞决策 查询人群包、频控、预算等策略数据，返回允许参竞的计划列表（code=0）。
  4. 元气智广执行投放决策 返回结果命中则继续投放流程；异常情况（超时、解析失败、必填缺失）本次请求将被跳过，无法参竞。
与转化跟踪的关系

RTA 解决「竞价前过滤」，转化跟踪解决「转化后回传」，两者独立、可并存。若您尚未完成转化跟踪对接，请先阅读转化跟踪对接指南。

接入前提

开始开发前，请确认具备以下条件：

  • HTTP 服务：可公网访问的接口，支持 POST + JSON（Content-Type: application/json），建议配置 IP 白名单
  • 策略数据源：人群包、频控、预算等决策数据的毫秒级查询能力（本地缓存 / 内存索引）
  • 容量评估：与元气智广确认预估峰值 QPS，并预留冗余
  • rtaIds 分配：rtaIds 由您的 RTA 服务分配，用于区分调用的 DMP 库——开发前先与元气智广确认分配给元气智广的 rtaId 列表
  • 技术联系人：用于联调排障对接

请求说明

元气智广在每次竞价时调用您提供的接口：

POST http://您的RTA服务地址（联调时确认）
  • 网络协议：HTTP POST，序列协议采用 JSON，Header："Content-Type": "application/json"
  • HTTP 状态码：200 为正常，其余状态码默认按异常处理
  • 响应时长：广告主侧需在 60ms 内返回结果（包括网络传输时间 + 内部处理时间）
  • 调用频率：与广告请求量同级，需按确认的峰值 QPS 承载
延迟是硬约束

RTA 处于竞价关键路径上。请务必将策略数据放在内存或本地缓存中，避免在 RTA 链路里做远程查询；一旦超时，本次请求将无法参竞。

请求字段

顶层字段

字段类型是否必填含义示例
reqIdstring 是 单次请求唯一标识 ID 2abd9780-511a-4549-b982-072dd9b5e198
rtaIdsint64[] 是 本次请求对应的 rta_id 列表。由您的 RTA 服务分配，用于区分调用的 DMP 库 [0, 1, 2]
devicestruct 有则必填 设备号结构体，见下表 —

device 结构体

字段类型是否必填含义示例
osint64是操作系统：0 未知设备 / 1 安卓设备 / 2 苹果设备1
osVersionint64否操作系统版本13
modelstring否机型Pixel 7
imeiMd5string否安卓设备 ID 的 MD5 加密，32 位小写6a347365d63ff0069082753748b8a825
oaidstring否oaid 原值，Android Q 及更高版本的设备号77CE527B70CB45AD…
oaidMd5string否oaid 的 MD5 加密，32 位小写—
androidIdstring否Android ID 原值864162033703542
idfastring否idfa 原值，iOS 6+ 的设备 ID 字段，32 位76B17F93-F503-4CF4-A05E-7A9FUECDA144
ipstring否设备 IP 地址112.224.33.246
userAgentstring否客户端 UAMozilla/5.0 (Linux; Android 13)…
caidstring否中广协 caid，主要用于识别 iOS 设备，最新版本值cb8dbf140e893a9ca30eb68981576a3b
caid2string否中广协 caid，主要用于识别 iOS 设备，上一个版本值0ba891db03cb7db0a826050f315cc3f4
设备标识传参约定
  • 安卓设备传：imeiMd5、oaid、androidId
  • iOS 设备传：idfa、caid、caid2
  • 有值都需要传，无值请设置为空字符串，具体以联调结果为准

响应格式

请以 HTTP 200 + JSON 响应：

响应字段定义

字段类型是否必填含义示例
reqIdstring是单次请求唯一标识 ID，和请求中的 reqId 相同2abd9780-511a-4549-b982-072dd9b5e198
codeint32是状态码：0 表示请求成功，其他表示错误0
rtaIdsint64[]是指定允许参竞的 rtaId 列表[1]

不同返回结果的处理逻辑

您的返回处理结果
code=0，rtaIds 命中允许参竞，进入投放流程
code=0，rtaIds 为空 / 未命中本次不参竞
code≠0本次请求被丢弃，无法参竞
超时 / 数据格式无法解析 / 必填字段缺失 / 非 200 状态码本次请求被丢弃，无法参竞

设备号加密规则

  1. 加密规则：imei 原值进行 MD5 加密（imeiMd5）；oaid / idfa / androidId / caid 原值发送
  2. 加密方法（Java 示例）：imeiMd5 = DigestUtils.md5Hex(imei).toLowerCase();
  3. 注意：当设备信息为空值时，直接不做填充
举例

imei：860264037477800
imeiMd5：27f356d483b2799e7fcb59255bf1cb99（32 位小写）

请求与返回示例

请求示例

request.json 
{
    "reqId": "2abd9780-511a-4549-b982-072dd9b5e198",
    "rtaIds": [0, 1, 2],
    "device": {
        "os": 1,
        "osVersion": 13,
        "model": "Pixel 7",
        "imeiMd5": "6a347365d63ff0069082753748b8a825",
        "oaid": "77CE527B70CB45AD991D8535BF94388914436004019A9D5BC74C30E80BE184F1",
        "androidId": "864162033703542",
        "idfa": "",
        "ip": "112.224.33.246",
        "userAgent": "ting_8.3.18(V1941A,Android29)",
        "caid": "",
        "caid2": ""
    }
}

返回示例

response.json — 仅 rtaId 1 允许参竞 
{
    "reqId": "2abd9780-511a-4549-b982-072dd9b5e198",
    "code": 0,        // 0：成功，其他表示错误
    "rtaIds": [1]   // 指定允许参竞的 rta_id 列表
}

步骤 1：开发 RTA 接口

按接口规范实现查询服务，重点满足以下要求：

  1. 协议与格式 HTTP POST + JSON，按上文字段表解析，缺省字段做容错；响应固定为 {reqId, code, rtaIds}，且 reqId 与请求保持一致
  2. 毫秒级决策 人群包、频控、预算等策略数据全部预载到内存 / 本地缓存，接口内部不做远程调用，确保 60ms 内（含网络传输）返回
  3. 无状态、可水平扩展 接口不依赖会话，相同输入返回一致结果，便于按 QPS 扩容
  4. 快速失败 内部异常时立即返回 code=0, rtaIds=[]，不要等待或重试上游依赖——快速返回空结果的影响远小于超时丢弃
  5. 日志与排障 记录 reqId / 收到的 rtaIds / 返回的 rtaIds，便于联调与线上对齐

步骤 2：登记接口信息

将以下信息提供给元气智广对接人：

  • 接口 URL：生产与测试环境各一套（建议）
  • 预估 QPS 承诺：可承载的峰值 QPS（元气智广侧将据此配置）
  • IP 白名单：如您的接口有访问限制，提供需放行的元气智广出口 IP
  • rtaIds 确认：确认分配给您用于区分 DMP 库的 rtaId 列表
  • 技术联系人：联调与故障升级通道

步骤 3：联调测试

  1. 模拟请求验证 元气智广发送样例请求，核对您的解析结果与响应格式；提供 reqId 便于双向对齐日志
  2. 延迟压测 按预估峰值 QPS 压测，确认 60ms 内返回且无错误率抬升
  3. 异常演练 验证：服务重启、依赖超时、返回 code≠0 等场景下，您的接口将被跳过，不会参与本次投放，符合预期
  4. 端到端验证 在测试链路发起真实广告请求，确认「参竞 → 投放 → 转化回传」全链路数据一致

步骤 4：上线与监控

  1. 灰度放量 先切小比例流量观察参竞率、延迟与错误率，稳定后逐步放量到全量
  2. 参竞效果监控 双方各自监控参竞率与错误率，异常时按时间点与 reqId 对齐日志
  3. 例行变更 接口 URL、扩缩容、证书更换等变更请提前 1 个工作日通知我们

异常处理

场景处理结果
响应超时（超过 60ms）本次请求被丢弃，无法参竞
返回数据格式无法解析（非 JSON / 非 200）本次请求被丢弃，无法参竞
必填字段缺失（reqId / code / rtaIds）本次请求被丢弃，无法参竞
code≠0本次请求被丢弃，无法参竞
设计含义

异常情况下一律丢弃不重试，因此请确保您的接口具备降级能力——任何内部异常都应立即返回 code=0, rtaIds=[]，由您的策略侧决定最终参竞行为，而非交给网络超时。

FAQ

响应时长 60ms 包含什么？

包含网络传输时间 + 您的内部处理时间。因此请把内部处理预算控制得更紧（建议 50ms 以内），给网络往返留余量。

超时后会重试吗？

不会。请确保您的接口在 60ms 内稳定返回，超时将导致本次请求无法参竞。

rtaIds 是什么？从哪里获取？

rtaIds 由您的 RTA 服务分配，用于区分调用的 DMP 库。开发前请与元气智广对接人确认您分配给元气智广的 rtaId 列表，并在返回中只使用这些 ID。

如何排障？

每次请求携带唯一 reqId。排障时提供 reqId 及大致时间点，双方即可对齐日志。

对接完成

恭喜！完成以上步骤后，您的 RTA 接口即进入正式服务状态。如有问题，请联系您的商务经理或技术支持。