JS 广告 SDK

本页介绍网站与 H5 使用的 JS SDK。原生 App 请参阅 Android、iOS 或 Flutter。

ADBNK 广告 SDK（v3）提供类似 Google AdSense 的极简接入方式：在页面里放一个广告位容器标签，再引入一行 SDK 脚本即可自动加载广告。SDK 会自动扫描广告位，为每个广告位加载并展示合适的广告。

快速开始

最小接入只需两步：放置广告位容器 + 引入 SDK。

html

<!-- 1. 在需要展示广告的位置放置广告位容器 -->
<ins class="adsbyadbnk"
     data-zone-id="zone_3887fe9a"
     style="display:block;width:300px;height:250px;">
</ins>

<!-- 2. 引入 SDK（位置不限，通常放在 </body> 前） -->
<script async src="https://js.adbnk.co/sdk.js"></script>

引入后，SDK 会自动完成：

扫描页面上所有 <ins class="adsbyadbnk"> 广告位元素（包括之后动态插入的）
为每个广告位加载并展示合适的广告

其中 data-zone-id 为广告位 ID：在流量主后台创建广告位后，在「获取代码」里复制（或直接复制整段代码）。zone_ 前缀可写可不写，zone_3887fe9a 与 3887fe9a 指同一个广告位。

Telegram 小程序

要在 Telegram 小程序里展示广告？请看 Telegram 小程序接入，其中提供了激励和插屏的编程式 API。

广告位容器

支持的标签格式

推荐使用 <ins> 标签，也支持 <div> 及 data-adbnk-zone 属性：

html

<!-- 推荐：ins 标签 + class -->
<ins class="adsbyadbnk" data-zone-id="zone_xxx" style="display:block;width:300px;height:250px;"></ins>

<!-- 也支持：div 标签 -->
<div class="adsbyadbnk" data-zone-id="zone_xxx" style="width:300px;height:250px;"></div>

<!-- 也支持：data-adbnk-zone 属性（后台「异步加载器」代码用的就是这种写法） -->
<ins class="adsbyadbnk" data-adbnk-zone="zone_xxx"></ins>

广告位属性

属性	必填	说明	示例
`data-zone-id`	是	广告位 ID	`zone_3887fe9a`
`data-width`	否	广告宽度（覆盖 CSS 宽度）	`300`
`data-height`	否	广告高度（覆盖 CSS 高度）	`250`
`data-responsive`	否	响应式广告位：铺满容器宽度，高度按素材比例自适应（后台响应式代码已带）	（无需取值）
`data-lazy`	否	是否懒加载。默认：设置了尺寸的广告位懒加载，没有设置尺寸的广告位立即加载	`true` / `false`
`data-ad-type`	否	后台为不在标签内展示的格式（弹窗、插屏、浮动、推送等）自动加上，用于不画占位框。请保持生成时的值	`POPUP`
`data-adbnk-nofill`	否	`keep` = 没有广告时保留广告框并显示「Advertisement」占位，而不是收起	`keep`
`data-reward-user-id` / `data-reward-custom-data`	激励位	见激励广告

页面内的广告位要设置尺寸

在页面内展示的广告位（横幅、原生、视频等）需要有明确的宽高（通过 style 或 data-width/data-height），或使用后台提供的响应式代码。它们在滚动到视口附近时加载。

由格式自己决定展示位置的广告（弹窗、插屏、浮动、推送等）使用后台提供的无尺寸代码，页面加载后立即加载，标签放在页面任何位置都可以。

渲染与广告类型

广告以可直接展示的形式返回，页面无需处理渲染，展示与点击由 SDK 自动上报。广告格式由你在后台选的广告位类型和素材决定，页面无需区分：

分组	格式
页面内（展示在标签内，需要尺寸）	横幅、原生、页面内视频、富媒体（基于模板的交互广告）
页面外（位置由格式决定，无需尺寸）	弹窗 / 背投、插屏、浮动 / 锚定条、推送 / 页内推送、悬浮视频、图标、激励

常见尺寸：300x250（中矩形）、728x90（横幅）、320x50（手机横幅）、300x600（半页）、970x250（公告牌）。更多格式说明见广告格式。

JavaScript API

SDK 加载后会在 window.adbnk 上挂载方法，用于手动控制广告位（如单页应用路由切换、瀑布流动态插入场景）。

手动刷新广告

// 刷新指定广告位（重新请求并渲染）
window.adbnk.refresh('zone_3887fe9a');

同一个广告位在页面上放了多个时，refresh(zoneId) 作用于最后登记的那一个。

手动添加广告位

符合上面标签格式的元素即使在页面加载后才插入，也会被自动识别。其他容器可用 push 主动注册：

window.adbnk.push({
  zoneId: 'zone_3887fe9a',
  container: '#ad-container'   // 元素 id 或 CSS 选择器
  // 或者直接传元素：element: document.getElementById('ad-container')
});

已经登记过的元素不会重复登记。

重新显示浮动广告

// 访客关闭浮动广告后，再次显示
window.adbnk.showFloat('zone_3887fe9a');

访客关闭浮动广告后，本次访问内 SDK 不会自行再显示；请只在你自己的界面里（如「显示广告」按钮）调用 showFloat。

追踪自动完成

展示与点击由 SDK 自动上报，无需手动埋点。

页面定向信息

SDK 会读取当前页面的地址、标题等公开信息，用于匹配相关广告，无需手动传参。

错误码

从 SDK 3.3.2 起，所有没有出广告或失败的结果都会带一个稳定的错误码。请用 code 决定如何处理，不要解析 message。

字段	说明
`code`	错误码名称，如 `NO_FILL`。请用它来决定如何处理
`message`	每个错误码对应的一句固定英文，只用于日志，请勿解析或比较
`retryable`	稍后重试是否值得
`zoneId`、`requestId`	已知时才有。联系支持时请附上 `requestId`
`fallbackShown`	仅 `NO_FILL` 时可能出现：为 `true` 表示广告位里正在显示你自己的后备内容

在哪里收到

标签式广告位：adbnk:result 事件。 广告位没有出广告就结束时，SDK 会在该广告位的 <ins> 元素上派发它（会冒泡）：无填充、请求失败、容器过小、达到你在广告位上设置的展示次数上限，或访客在激励广告完成前关闭了广告。广告正常展示时不会派发。

document.addEventListener('adbnk:result', function (e) {
  var r = e.detail; // { code, message, retryable, zoneId, requestId?, fallbackShown? }
  if (r.code === 'NO_FILL' && !r.fallbackShown) hideMyAdWrapper(e.target);
});

激励广告位：adbnk:reward_unverified。 它的 detail（以及 window.onAdbnkRewardUnverified 的参数）也带有 code、message、retryable，已知时还有 requestId。它不代表奖励，见激励广告。旧的 reason 字段只为兼容保留，请改用 code 判断。

Telegram 小程序： window.adbnk.telegram.init(...) 返回的错误带有同样的 code、message 和 retryable。见 Telegram 小程序，那里也说明了已弃用的兼容字段 e.legacyCode。

全部错误码

错误码	可重试	含义	处理建议
`NO_FILL`	是	暂时没有合适的广告。	隐藏容器或展示自己的内容;可以稍后重试,不建议高频重试。
`NOT_READY`	是	广告还没准备好展示。	等加载完成后再展示;页面回到前台后再试。
`LOAD_IN_PROGRESS`	是	同一个广告对象正在加载或展示中。	等当前操作结束后再调用。
`ALREADY_SHOWN`	否	这条广告已经展示过。	重新加载一条新广告。
`EXPIRED`	否	这条广告已过期。	重新加载一条新广告。
`NETWORK_ERROR`	是	请求没有成功返回。	检查网络后稍后重试。
`TIMEOUT`	是	请求超时。	稍后重试。
`INVALID_ZONE`	否	版位不存在、未启用,与调用的接口类型不符,或请求参数无效。	检查广告位代码(不是数字 ID)、版位类型和传入参数,例如不要把横幅版位当作激励版位使用,`custom_data` 不超过 500 个字符。
`UNSUPPORTED_ENV`	否	当前环境无法展示这种广告形式。	不要在该环境下请求这种广告形式。
`CONTAINER_TOO_SMALL`	否	容器放不下这个尺寸的广告。	加宽容器后重新请求,或改用自适应尺寸的版位。
`USER_DISMISSED`	否	用户在完成前关闭或跳过了广告。	不发放奖励;不要立刻再次弹出,等下一个合适的时机。
`REWARD_UNVERIFIED`	否	奖励未能验证。	不要仅凭客户端结果发放有价值的奖励;以服务端验证或服务端回调为准。
`FREQUENCY_CAP_REACHED`	否	已达到你为该广告位设置的展示次数上限。	本周期内不再请求或展示该广告位；可提示用户稍后再试。上限在流量主后台的广告位设置中调整。
`NOT_ELIGIBLE`	否	当前请求不满足发放条件。	不发放奖励。
`OBJECT_RELEASED`	否	广告对象已被销毁。	创建新的广告对象。
`INTERNAL_ERROR`	是	发生未知错误。	稍后重试;持续出现请联系支持并提供 `requestId`。

奖励接口

SDK 的领奖请求（/ad/reward/token）或你的服务端核验（POST /ad/reward/verify）被拒绝时，返回的 JSON 在 HTTP 错误状态之外还有一个顶层字段 error_code，取值是上表中的四个：

`error_code`	含义
`NOT_ELIGIBLE`	当前请求不满足发放条件。
`NOT_READY`	尚未就绪。
`INVALID_ZONE`	版位或请求参数无效。在 `/ad/reward/verify` 上，缺少或格式错误的参数也返回它。
`INTERNAL_ERROR`	服务端错误（HTTP 500），稍后重试。

只要响应里带 error_code，就表示“不要发放”：SDK 会把它当作未确认的奖励上报。这类响应里的 message 文本是固定的，只用于日志。

从 v2 迁移

变化	v2	v3
容器标签	`<div data-adbnk-zone="zone_xxx">`	`<ins class="adsbyadbnk" data-zone-id="zone_xxx">`（`data-adbnk-zone` 仍可用）
脚本	`async.js` + `ADBNK_CONFIG`	`sdk.js`（不再使用 `async.js` 与 `ADBNK_CONFIG`）

升级到 3.3

破坏性变化（3.3.0 起）：未确认的奖励不再调用 onAdbnkReward。 奖励未能得到服务端确认时，旧版会以 { unsigned: true } 调用 window.onAdbnkReward；现在只派发 adbnk:reward_unverified 事件（若你定义了 window.onAdbnkRewardUnverified 也会调用它）。adbnk:reward 和 onAdbnkReward 只在奖励确认后触发。

如果你的页面在 onAdbnkReward 里判断过 reward.unsigned，请把这段处理移到 adbnk:reward_unverified。无论哪种情况，有价值的奖励都只应依据服务端回调或服务端核验发放，见激励广告。

故障排除

广告不显示时，请依次检查：

data-zone-id 是否正确，广告位是否已审核通过并处于启用状态
sdk.js 是否成功加载（Network 面板确认 js.adbnk.co/sdk.js 200）？广告拦截插件可能拦截它
页面内广告位的容器是否有有效宽高
是否只是暂时没有可投放的广告？无填充时广告位会收起（不占位置），SDK 稍后自动重试。如希望保留广告框，加 data-adbnk-nofill="keep"

安全说明

广告在沙箱 iframe 中渲染，广告代码无法访问宿主页面的 DOM 和 Cookie。

JS 广告 SDK ​

快速开始 ​

广告位容器 ​

支持的标签格式 ​

广告位属性 ​

渲染与广告类型 ​

JavaScript API ​

手动刷新广告 ​

手动添加广告位 ​

重新显示浮动广告 ​

页面定向信息 ​

错误码 ​

在哪里收到 ​

全部错误码 ​

奖励接口 ​

从 v2 迁移 ​

升级到 3.3 ​

故障排除 ​