广告请求 API

为广告位实时请求广告。接口前缀为 /ad，无需鉴权。

优先使用 SDK

JS 广告 SDK 与各原生 SDK 会替你调用本接口，并处理展示与点击追踪。本页面向直接调用接口的集成方。

请求前需先在流量主后台创建广告位并获取 zone_key（形如 zone_ab12cd34），见流量主 API · 广告位。

请求广告

GET https://aapi.adbnk.co/ad/request 或 POST https://aapi.adbnk.co/ad/request

参数可放在 query string、JSON body 或表单 body 中。

参数	类型	必填	说明
`zone`	string	是*	广告位编码 `zone_key`
`zone_id`	int	是*	广告位数字 ID（两者都传时以它为准）
`limit`	int	否	返回广告数量，1–5，默认 1（超出范围按 1 处理）
`page_url`	string	否	广告所在页面 URL
`page_title`	string	否	页面标题
`page_keywords`	string	否	页面关键词
`page_category`	string	否	页面分类
`page_type`	string	否	页面类型（`article`/`video`/`product` 等）
`page_tags`	string	否	页面标签，逗号分隔
`page_lang`	string	否	页面语言；同时决定渲染出的 `html` 使用的语言
`keywords`	string / string[]	否	额外的内容关键词
`content_url`	string	否	内容 URL

* zone 与 zone_id 二选一必填。

隐私信号（均为可选；有就请传）：

参数	类型	说明
`gdpr`	0 / 1	是否适用 GDPR
`gdpr_consent`	string	IAB TCF v2 同意字符串
`us_privacy`	string	IAB US Privacy（CCPA）字符串
`gpp` / `gpp_sid`	string	IAB GPP 字符串 / 适用的 section ID
`npa`	0 / 1	`1` = 只投非个性化广告
`tag_for_child_directed`	0 / 1	面向儿童处理
`tag_for_under_age`	0 / 1	未达同意年龄

设备数据由 ADBNK SDK 自动采集。为获得更好的填充和统计效果，建议通过 SDK 接入。

也支持路径形式：GET / POST /ad/request/{zone_key}（zone_ 前缀可省略）。

bash

curl "https://aapi.adbnk.co/ad/request?zone=zone_ab12cd34&limit=1&page_url=https%3A%2F%2Fblog.example.com%2Fpost%2F1"

展示与点击由 SDK 测量；单独请求广告不产生计费。

一次请求多个广告位

POST 一个带 zones 数组的 JSON body，每项带 zone_key 或 zone_id（上面的其他参数对所有广告位生效）：

json

{ "zones": [ { "zone_key": "zone_ab12cd34" }, { "zone_id": 6 } ], "page_url": "https://blog.example.com/post/1" }

响应为 data: { "batch": true, "results": [ ... ] }。每个 result 是一个广告位块，结构与单广告位的 data（见下文）相同，另加 zone_key 和 zone_id。无法投放的广告位为 ads: [] 并带 error 字符串（zone_not_found、zone_unavailable 或其他值；任何带 error 的都按该广告位无填充处理）。

返回结构

json

{
  "code": 0,
  "message": "success",
  "data": {
    "schema_version": 2,
    "min_sdk_version": "1.0.0",
    "capabilities": ["deeplink", "mraid", "native_obj"],
    "request_id": "req_8f3a2c9d1e7b",
    "zone": {
      "id": 5,
      "code": "zone_ab12cd34",
      "width": 300,
      "height": 250,
      "type": "BANNER",
      "device": "ALL",
      "refresh": 0
    },
    "ads": [
      {
        "id": "q1w2e3r4t5y6...",
        "ad_id": 1001,
        "creative_id": 2001,
        "campaign_id": 3001,
        "zone_id": 4001,
        "type": "IMAGE",
        "title": "夏季大促",
        "description": "全场 5 折起",
        "button_text": "立即选购",
        "brand_name": "Example Shop",
        "image_url": "https://imgs.abnk-res.top/creatives/1.jpg",
        "image_url_2": "",
        "video_url": "",
        "icon_url": "",
        "display_url": "example.com",
        "landing_url": "https://example.com/sale",
        "click_url": "https://track.adbnk.co/track/click/q1w2e3r4t5y6...",
        "deeplink": null,
        "fallback_url": null,
        "impression_url": "https://track.adbnk.co/track/impression/q1w2e3r4t5y6...",
        "width": 300,
        "height": 250,
        "html": "<!DOCTYPE html>...<span class=\"ad-badge\">AD</span>..."
      }
    ]
  },
  "timestamp": 1752200000
}

字段	说明
`schema_version`	响应结构版本（当前为 `2`）。新增字段不会升版本——不认识的字段请忽略。
`min_sdk_version`	能解析本响应的最低 SDK 版本
`capabilities`	本响应支持的能力（`deeplink`、`mraid`、`native_obj`）
`request_id`	请求标识；联系支持时请附上
`zone`	广告位配置，见广告位对象
`ads`	待展示的广告；无填充时为空

data 中可能还有本文未列出的字段，请忽略。

无填充

无可用广告时 code 仍为 0，data.ads 为空数组；请以 ads 判断，不要看 message。Web（非 App）请求还可能在 data.retry 中带重试提示：

json

"retry": { "after_ms": 30000, "max": 1 }

至少等待 after_ms 毫秒再重新请求，最多重试 max 次（0 = 不重试）。

错误

`code`	`message_key`	含义
`400`	`error.ad.zone_param_missing`	`zone` 与 `zone_id` 都没传
`404`	`error.ad.zone_not_found`	广告位不存在
`403`	`error.ad.zone_unavailable`	广告位已停用或尚未通过审核
`500`	`error.internal`	服务端错误，请稍后重试

错误响应的 data 为 null。请以 body 中的 code 字段判断成败（0 = 成功），出错时 HTTP 状态也可能是 200。message 是可能被本地化的可读文案，请按 message_key 匹配。任何非 JSON 或 5xx 响应都按暂时无填充处理。

creative 结构

ads[] 中每一项是一个可展示的广告。没有值的字段为 null、空字符串或不出现。广告上也可能带本文未列出的字段，请忽略。

字段	类型	说明
`id`	string	不透明的广告标识，请勿解析
`ad_id` / `creative_id` / `campaign_id` / `zone_id`	int	数字 ID，供你自己记日志和报表
`type`	string	创意类型，如 `IMAGE` / `NATIVE` / `VIDEO` / `RICH_MEDIA`。以后可能新增；无法展示的类型请跳过
`title` / `description`	string	标题 / 描述文案
`button_text`	string	行动号召文案
`brand_name`	string	品牌名
`image_url` / `image_url_2`	string	图片 URL
`video_url`	string	视频 URL
`icon_url`	string	图标 URL
`display_url`	string	向用户展示的显示 URL
`landing_url`	string	广告主落地页，仅供展示，可能为 `null`。不要直接把用户送到这里。
`click_url`	string	点击 URL。用户点击时打开它，会重定向到落地页。每次点击最多使用一次。
`deeplink`	string	优先尝试唤起的 App 深链（有则下发）
`fallback_url`	string	深链唤起失败时的去处（只与 `deeplink` 同时出现）
`impression_url`	string	展示追踪 URL
`width` / `height`	int	创意尺寸
`html`	string	渲染好的完整广告 HTML，可直接放进 iframe/WebView 展示
`native`	object	`NATIVE` 广告的结构化素材（见下）
`html_content`	string	`RICH_MEDIA` 广告渲染好的模板内容，供 WebView 展示（存在时）

native 对象：title、description、sponsor、cta_text、icon（URL）、image（URL）、rating（1–5）、price、likes。任一项都可能为 null。

带深链的点击：先请求 click_url，再尝试 deeplink。深链打不开时，依次去 fallback_url、landing_url，都没有则去 click_url 重定向到的页面。

展示与点击追踪

impression_url 与 click_url 请原样使用：不要修改、预取或重放。展示与点击由 SDK 处理。详见事件与转化上报。

广告位对象

data.zone 总是包含 id、code、width、height、type、device（PC / MOBILE / ALL）和 refresh（自动刷新间隔，秒，0 = 不刷新）。部分广告位类型还带有在流量主后台配置的展示设置（触发方式、频次、关闭按钮等），由 SDK 自动处理，直接调用时可忽略。

VAST 视频广告

GET https://aapi.adbnk.co/ad/render/vast/{zone_key}

返回 VAST XML，供支持 VAST 的视频播放器使用。默认返回 3.0 版本；加 vast=4 返回 VAST 4.2。无广告时返回空的 <VAST> 文档。视频广告位可直接使用的 VAST 标签请在流量主后台「获取代码」里复制。需要前贴/中贴/后贴排期时，在同一处复制 VMAP 标签。

参数	说明
`vast`	`4` = VAST 4.2（默认 3.0）
`skip`	`1` = 线性广告可跳过
`linear` / `nonlinear` / `companion`	`0` = 不包含该类创意

激励广告

用户看完激励广告后，SDK 会通知你的页面，由你发放奖励：

html

<script>
  // 定义全局回调……
  window.onAdbnkReward = function (reward) {
    // reward.zoneId、reward.userId、reward.customData、reward.rewardAmount、
    // reward.rewardType、reward.transactionId、reward.timestamp、
    // reward.signature、reward.keyId（发给你的服务端核验奖励）
  }
  // ……或监听事件
  document.addEventListener('adbnk:reward', function (e) { /* e.detail 字段相同 */ })
</script>

在激励广告位标签上加 data-reward-user-id（以及可选的 data-reward-custom-data）——后台「获取代码」已带这些属性；它们会原样回传给你。
每个 transactionId 最多发奖一次。
只对带有 transactionId 的回调发放奖励。
自定义数据最长 500 个字符，超长会返回 400，不会发放奖励；用户 ID 超过 255 个字符时截断为 255 个。

奖励确认后，adbnk:reward / onAdbnkReward 还会带上 verified: true、adId、requestId 和 signedFieldsComplete。所有 ID 字段（zoneId、adId、requestId、transactionId、keyId）都是字符串。signedFieldsComplete 为 false 表示部分字段取自页面发出的值，而不是我们服务端返回的值；没有这类值的字段（例如 rewardAmount、rewardType、timestamp）此时可能不存在。

如果浏览器端未能确认奖励，SDK 不会派发 adbnk:reward，而是派发 adbnk:reward_unverified（如果你定义了 window.onAdbnkRewardUnverified，也会调用它），detail 为 { zoneId, verified: false, transactionId: null, reason, timestamp, code, message, retryable }（已知时还有 requestId）。reason 为 unverified 或 not_eligible，只为兼容保留，请改用 code（见错误码）；timestamp 为浏览器时间（毫秒）。每次展示最多派发这两个事件中的一个。

两个事件都不能证明奖励成立

adbnk:reward_unverified 从不代表奖励，adbnk:reward 也只是浏览器端的声明。有价值的奖励只能按服务端签名回调（SSV）发放，或在你的服务端核验后发放（见下文）。

在服务端核验奖励

发放有价值的奖励之前，请在你的服务端核验。把奖励里的 transactionId、signature、keyId 发给你的服务端，再由你的服务端调用：

POST https://api.adbnk.co/ad/reward/verify

这个接口在平台 API 主机 api.adbnk.co 上，不在上文的广告请求主机上。

参数	类型	必填	说明
`transaction_id`	string	是	奖励里的 `transactionId`
`signature`	string	是	奖励里的 `signature`，原样传入
`key_id`	string	否	奖励里的 `keyId`。建议传，原因见下方的失败规则

请求体（JSON）：

json

{ "transaction_id": "rt_9f2c…", "signature": "…", "key_id": "…" }

奖励有效时，响应有两种形态。通常能在平台记录中找到这笔奖励，响应带完整记录：

json

{
  "code": 0,
  "data": {
    "valid": true,
    "transaction_id": "rt_9f2c…",
    "zone_id": "12345",
    "ad_id": "…",
    "request_id": "…",
    "user_id": "u123",
    "custom_data": "",
    "reward_amount": 10,
    "reward_type": "coin",
    "issued_at": "2026-10-06T08:15:30Z",
    "verified_at": "2026-10-06T08:15:31Z"
  }
}

少数情况下改为通过核对签名确认奖励（需要传 key_id），此时响应只有 valid 和 transaction_id：

json

{ "code": 0, "data": { "valid": true, "transaction_id": "rt_9f2c…" } }

不要假定 zone_id、user_id 等记录字段一定存在。

这些字段来自平台对这笔奖励的记录，与签名时的值完全一致，而不是来自你的请求。请以它们为准，不要用浏览器端的值。
zone_id 是广告位的数字 ID，以十进制字符串返回。空值可能返回 "" 或 null，两者都按空值处理。issued_at、verified_at 为 UTC 时间，ISO 8601 格式，以 Z 结尾。
传了 key_id 时，交易不存在和签名不匹配都返回 {"valid": false, "transaction_id": "…"}，不带其他字段，也不会说明是哪一项不通过。
没传 key_id 且奖励无法匹配时，请求会直接返回 400（"Missing required parameters"）。如果希望失败时统一得到 {"valid": false}，请传 key_id。
请确认 zone_id、user_id 是你预期的值，并且每个 transaction_id 只发一次奖：对同一笔奖励再次核验仍会返回 valid: true。
缺少 transaction_id 或 signature 时返回 400。

SDK 拿到的奖励带有被签名的字段 zone_id、ad_id、request_id、user_id、custom_data（与签名时的值一致），以及 transaction_id、signature、key_id。在你的服务端核验之前，请只把它当作一个待确认的声明。

Telegram 小程序

在 Telegram 小程序中，激励和插屏广告由你的代码调用展示：

window.adbnk.telegram.init({ zoneId: 'zone_xxxxxxxx', userId: 'u123' }).show()
  .then(function (result) { /* 更新界面；发奖以服务端回调为准 */ })
  .catch(function (e) { /* e.code 是公开错误码，如 NO_FILL、USER_DISMISSED、REWARD_UNVERIFIED；e.legacyCode 保留原来的小写名称（no_fill、closed、skipped、busy、wrong_format、reward_failed、not_active、destroyed、error） */ })

Telegram 广告位的服务端回调在能取到时还会带上 tg_user_id（Telegram 用户 ID）。它和其他参数一样参与签名：验签时使用除 signature、key_id 以及你配置的回调地址里原本就带的参数之外的全部查询参数——这几类参数不参与签名。完整 API、错误码和验签方法见 Telegram 小程序接入。

服务端校验

服务端签名奖励回调（SSV）在激励广告位上配置回调地址后生效。客户端事件不代表可信奖励：adbnk:reward_unverified 和 Telegram 的 reward_failed 错误从不代表奖励，adbnk:reward 也只是浏览器端的声明。无论是否配置了回调地址，发奖都只能依据 SSV 回调，或你的服务端调用 POST https://api.adbnk.co/ad/reward/verify 核验成功的结果（见在服务端核验奖励）。

广告请求 API ​

请求广告 ​

一次请求多个广告位 ​

返回结构 ​

无填充 ​

错误 ​

creative 结构 ​

广告位对象 ​

VAST 视频广告 ​

激励广告 ​

在服务端核验奖励 ​

Telegram 小程序 ​

广告请求 API

请求广告

一次请求多个广告位

返回结构

无填充

错误

creative 结构

广告位对象

VAST 视频广告

激励广告

在服务端核验奖励

Telegram 小程序