JS 广告 SDK

ADBNK 广告 SDK（v3）提供类似 Google AdSense 的极简接入方式：在页面里放一个广告位容器标签，再引入一行 SDK 脚本即可自动加载广告。SDK 会自动扫描广告位、提取页面定向信息、懒加载并在沙箱 iframe 中安全渲染广告。

三个域名各司其职

• https://js.adbnk.co — SDK 脚本分发（sdk.js）
• https://ad.adbnk.co — 广告请求接口（/ad/request）
• https://track.adbnk.co — 展示 / 点击 / 转化追踪

快速开始

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

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

<!-- 2. 在页面底部（</body> 前）引入 SDK -->
<script async src="https://js.adbnk.co/sdk.js"></script>

引入后，SDK 会自动完成：

• 扫描页面上所有 <ins class="adsbyadbnk"> 广告位元素
• 提取页面 meta / Open Graph / JSON-LD 信息用于广告定向
• 懒加载广告（元素进入视口时才真正请求）
• 使用 sandbox iframe 隔离渲染广告，保护宿主页面

其中 data-zone-id 为广告位 ID，请在流量主后台创建广告位后获取。

广告位容器

支持的标签格式

推荐使用 <ins> 标签，也兼容 <div> 及旧版属性：

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

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

<!-- 兼容旧版属性 -->
<div data-adbnk-zone="zone_xxx"></div>

广告位属性

属性	必填	说明	示例
data-zone-id	是	广告位 ID	3887fe9a
data-width	否	广告宽度（覆盖 CSS 宽度）	300
data-height	否	广告高度（覆盖 CSS 高度）	250
data-lazy	否	是否懒加载，默认 true	true / false

务必给容器设置尺寸

广告位需要有明确的宽高（通过 style 或 data-width/data-height）。否则懒加载可能因为高度为 0 无法正确判断视口，导致广告不加载。

初始化参数

如需自定义全局行为，在引入 sdk.js 之前声明 window.adbnk 配置对象：

<script>
  window.adbnk = {
    debug: false,                     // 开启后控制台输出 [ADBNK] 前缀调试日志
    apiUrl: 'https://ad.adbnk.co',    // 广告请求接口地址
    timeout: 10000                    // 单次请求超时（毫秒）
  };
</script>
<script async src="https://js.adbnk.co/sdk.js"></script>

参数	类型	默认值	说明
debug	boolean	false	开启调试日志
apiUrl	string	https://ad.adbnk.co	广告请求接口地址
timeout	number	10000	请求超时时间（毫秒）

渲染与广告类型

SDK 请求 https://ad.adbnk.co/ad/request 后，服务端返回已渲染好的完整 HTML，SDK 直接注入 sandbox iframe 展示。展示、点击的追踪 URL 已内置在返回的 HTML 中，无需前端额外处理。广告请求接口的完整参数见 广告请求 API。

支持的广告类型（由广告位类型和创意决定，前端无需区分）：

类型	说明
BANNER	图片横幅广告，支持各种标准尺寸
NATIVE	与页面内容融合的原生广告
VIDEO	视频广告（默认静音自动播放）
RICH_MEDIA	基于模板的交互式富媒体广告

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

JavaScript API

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

手动刷新广告

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

手动添加广告位

对于动态生成的容器，可用 push 主动注册：

window.adbnk.push({
  zoneId: '3887fe9a',
  container: '#ad-container'
  // 或者直接传元素：element: document.getElementById('ad-container')
});

追踪自动内置

展示（impression）与点击（click）的追踪逻辑已经内置在服务端返回的广告 HTML 中，通过 track.adbnk.co 自动上报，前端无需手动埋点。若要上报转化，请参见 转化追踪 SDK。

页面定向信息

SDK 会自动从页面提取以下信息随广告请求上报，用于提升广告相关度，你无需手动传参：

<!-- Open Graph -->
<meta property="og:title" content="文章标题">
<meta property="og:type" content="article">

<!-- 标准 meta -->
<meta name="keywords" content="关键词1, 关键词2">
<meta name="description" content="页面描述">

<!-- JSON-LD 结构化数据 -->
<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "Article",
  "headline": "文章标题", "keywords": ["AI", "机器学习"] }
</script>

设备指纹使用开源库 FingerprintJS v4 自动采集，无需手动设置。

从 v2 迁移

变化	v2	v3
容器标签	<div data-adbnk-zone="zone_xxx">	<ins class="adsbyadbnk" data-zone-id="xxx">
脚本	async.js + ADBNK_CONFIG	sdk.js（无需 ADBNK_CONFIG）
渲染	客户端渲染	服务端返回渲染好的 HTML

故障排除

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

1. data-zone-id 是否正确、广告位是否处于启用状态
2. sdk.js 是否成功加载（Network 面板确认 js.adbnk.co/sdk.js 200）
3. 容器是否有有效宽高
4. 开启调试模式查看控制台 [ADBNK] 日志：

<script>window.adbnk = { debug: true };</script>
<script async src="https://js.adbnk.co/sdk.js"></script>

安全说明

所有广告都在 sandbox iframe 中渲染，sandbox 限制为 allow-scripts allow-popups，广告代码无法访问宿主页面 DOM 或 Cookie。