@adrop/ads-web-sdk

中文文档

1.4.0发布于 2026/10/19Apache-2.0TypeScriptES Module零依赖近 30 天下载 2995

丢弃 Ads 网络 SDK

文档目录26 节

特征
安装
国家预防机制
光盘N
快速启动
1. 初始化SDK
2. 装货封装广告
3. 装入原生广告
4. 事件处理
高级使用
更新属性
正在本地主机上验证 Live Ads
目标设定
主题支持
装入回填广告
清除广告
重新装入广告
用户名
更新用户代号
配置选项
初始化选项
请求选项
活动
类型脚本支持
SPA 支持
许可证

丢弃 Ads 网络 SDK

官方Web SDK为滴放广告平台. 将直接交易广告无缝地整合到您的网络应用程序中.

特征

npm 和 CDN 的简单集成
QQ Banner 和本地广告格式
直接交易广告
iframe 安全广告渲染
* 内建事件跟踪
QQ 自定义本地广告渲染
轻量级和表演者
QQ 类型脚本支持

安装

国家预防机制

npm install @adrop/ads-web-sdk

光盘N

<script src="https://cdn.jsdelivr.net/npm/@adrop/ads-web-sdk@latest/dist/adrop-ads.min.js"></script>

快速启动

1. 初始化SDK

import Adrop from '@adrop/ads-web-sdk';

const adrop = Adrop.observe({
  appId: 'your-app-id',
  uid: 'your-user-id', // Logged-in users only — see "User ID"
  debug: true // Set to false in production
});

对于CDN的使用:

<script>
  const adrop = Adrop.observe({
    appId: 'your-app-id',
    uid: 'your-user-id', // Logged-in users only — see "User ID"
    debug: true
  });
</script>

自动加载( 声明式)

<div data-adrop-unit="YOUR_UNIT_ID"></div>

SDK在元素中自动检测并加载广告 data-adrop-unit 属性.

可选数据属性 :

data-adrop-context-id: 背景目标的背景标识
data-adrop-keywords: 关键词目标的关键字(已合并分离)
data-adrop-theme: 光/暗模式的主题(值: light, (中文(简体) ), dark(中文(简体) )

<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-context-id="CONTEXT_ID"
  data-adrop-theme="dark">
</div>

程序加载

const container = document.getElementById('ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_UNIT_ID'
});

SDK自动检测并制作本土广告.

可选字段 :

contextId: 背景目标的背景标识
keywords:关键词目标关键词(string[] 或逗号分隔字符串)
theme: 光/暗模式的主题(值: light, (中文(简体) ), dark(中文(简体) )

const container = document.getElementById('ad-container');

await adrop.renderAd(container, {
    unit: 'YOUR_UNIT_ID',
    contextId: 'CONTEXT_ID',
    theme: 'dark'
});

3. 装入原生广告

本地广告提供定制的广告体验与你的应用内容无缝融合。它们需要使用 data-adrop-native 属性.

自动装入自定义 UI (声明式)

要使用自定义 UI, 您必须设置 data-adrop-render="custom"数字 :

<div data-adrop-unit="YOUR_NATIVE_UNIT_ID" data-adrop-render="custom">
  <!-- Native ad components with data-adrop-native attributes -->
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" class="ad-profile-logo" alt="Profile">
    <span data-adrop-native="profile.displayName" class="ad-profile-name"></span>
  </div>
  <h3 data-adrop-native="headline" class="ad-headline"></h3>
  <img data-adrop-native="asset" class="ad-image" alt="Ad Image">
  <p data-adrop-native="body" class="ad-description"></p>
  <button data-adrop-native="callToAction" class="ad-cta-button"></button>
</div>

整个区域点击功能 :

<div 
  data-adrop-unit="YOUR_NATIVE_UNIT_ID" 
  data-adrop-render="custom"
  data-adrop-entire-click="true">
  <!-- Entire container becomes clickable -->
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" class="ad-profile-logo" alt="Profile">
    <span data-adrop-native="profile.displayName" class="ad-profile-name"></span>
  </div>
  <h3 data-adrop-native="headline" class="ad-headline"></h3>
  <img data-adrop-native="asset" class="ad-image" alt="Ad Image">
  <p data-adrop-native="body" class="ad-description"></p>
  <span data-adrop-native="callToAction" class="ad-cta-text"></span>
</div>

程序加载自定义 UI

const container = document.getElementById('native-ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_NATIVE_UNIT_ID',
  trackMode: 1 // Required for custom UI
});

整个区域点击功能 :

const container = document.getElementById('native-ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_NATIVE_UNIT_ID',
  trackMode: 1, // Required for custom UI
  isEntireClick: true // Makes entire container clickable
});

可用的数据投放本地字段

SDK支持以下内容: data-adrop-native 属性 :

基本领域 :

headline: 标题文本
body: 附加说明文本
callToAction: 呼叫到动作按钮文本
asset: 主广告图像 URL

配置字段(供广告商参考):

profile.displayLogo: 广告标志图像 URL
profile.displayName: 广告名称文本

额外字段( 海关属性 ) :

extra.{key}: 从ad数据自定义字段(例如, extra.price, (中文(简体) ), extra.rating(中文(简体) )

Media Slot 字段( 有多媒体的单位):

extraAssets.{id}.asset: 媒体槽 URL 绑定到一个 <img> (例如, extraAssets.m2.asset(中文(简体) )
extraAssets.{id}.cover: 视频插槽海报图像 URL(例如, extraAssets.m2.cover(中文(简体) )

自定义 UI 执行示例

<div data-adrop-unit="YOUR_NATIVE_UNIT_ID" data-adrop-render="custom" class="native-ad-container">
  <!-- Advertiser Profile -->
  <div class="advertiser-info">
    <img data-adrop-native="profile.displayLogo" class="advertiser-logo" alt="Advertiser">
    <span data-adrop-native="profile.displayName" class="advertiser-name"></span>
  </div>
  
  <!-- Ad Content -->
  <div class="ad-content">
    <h2 data-adrop-native="headline" class="ad-title"></h2>
    <img data-adrop-native="asset" class="ad-main-image" alt="Ad">
    <p data-adrop-native="body" class="ad-text"></p>
    
    <!-- Custom Fields -->
    <div class="ad-extras">
      <span data-adrop-native="extra.price" class="price-tag"></span>
      <span data-adrop-native="extra.rating" class="rating"></span>
    </div>
    
    <button data-adrop-native="callToAction" class="cta-button"></button>
  </div>
</div>

媒体槽( O)`extraAssets`(中文(简体) )

当一个本地单位定义媒体插槽时, adData.extraAssets (单位:千美元) adReceived 编号 : adImpression 编号 : adClicked 回调和输入 requestAd() 编号 : requestAds() 结果)持有由槽ID键入的每一个槽- { id, asset, ad, cover?, type?, isVideo }。。。 . asset 是媒体 URL, ad 是该槽的已渲染的 HTML( 意思与 adData.ad, (中文(简体) ), cover 是视频插槽的海报图像, type 是服务器所报的创建介质( y)'display' | 'video';没有老的答复) isVideo 实值 true 何时 type 实值 'video' 或,何时 type 缺席, 当 cover 存在或 asset 结尾 .mp4 编号 : .m3u8。第一个插槽与 adData.asset 编号 : adData.ad. 单媒体创作(没有插槽)和没有媒体的广告——读取主媒体 adData.asset 编号 : adData.ad。。。 .

adrop.on(Adrop.Events.AD_RECEIVED, (unit, adData) => {
  const slot = adData.extraAssets?.m2;
  if (slot?.isVideo) {
    console.log(slot.asset, slot.cover); // video URL, poster URL
  }
});

点击行为控制

您可以在本地广告中控制如何处理点击:

个人元素点击( 默认) :

仅包含元素 data-adrop-native 可单击属性
每个文本和图像元素处理自己的点击

全部区域点击 :

设定 data-adrop-entire-click="true" (声明)或 isEntireClick: true (方案)
整个广告容器可以点击
用于卡片样式的布局,其中广告的任何部分都应点击

重要注释 :

自定义用户界面要求 data-adrop-render="custom" 或者说 trackMode: 1
单击行为 : isEntireClick: true 使整个区域可以单击,否则只允许单个元素
SDK 自动处理点击跟踪和印象跟踪
要件 data-adrop-native 将自动包含广告内容
缺失的字段将留空( 没有出错)
配置文件点击重定向到广告主页面, 其他点击到广告登陆页面

4. 事件处理

听广告生命周期事件:

// Ad received successfully
adrop.on(Adrop.Events.AD_RECEIVED, (unit, adData) => {
  console.log('Ad received:', unit, adData);
});

// Ad failed to load
adrop.on(Adrop.Events.AD_FAILED, (unit) => {
  console.error('Ad failed:', unit);
});

// No ad available
adrop.on(Adrop.Events.AD_NO_FILL, (unit) => {
  console.warn('No ad available:', unit);
});

// No backfill ad available
adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {
  console.warn('No backfill ad available:', unit);
});

// Ad impression
adrop.on(Adrop.Events.AD_IMPRESSION, (unit, adData) => {
  console.log('Ad impression:', unit, adData);
});

// Ad clicked
adrop.on(Adrop.Events.AD_CLICKED, (unit, adData) => {
  console.log('Ad clicked:', unit, adData);
});

高级使用

更新属性

属性可以连锁并一起使用单调:

// Set app key
adrop.appKey = 'YOUR_APP_KEY';

// Chain multiple property updates and commit once
await adrop.metrics
  .setUserProperties({
    last_login: new Date().toISOString(),
    age: '25',
    gender: 'M',
    // Custom properties can be added directly
    theme: 'dark',
    language: 'en'
  })
  .setAppProperties({
    version: '1.0.0',
    platform: 'web'
  })
  .commit();

正在本地主机上验证 Live Ads

服务页数 localhost 实收 测试广告 默认。为了在部署前验证真实的广告投递情况, 设定 liveAds: true 与你的 appKeySDK然后用应用密钥认证,就像本地SDK一样.

const adrop = Adrop.observe({
  appId: 'your-app-id',
  appKey: 'your-app-key',
  liveAds: true
});

印象和点击的计算与制作时完全相同 给广告商开账单完成后将其关闭,或者将IP注册为控制台的测试者,以接受测试运动取而代之.
只在已送达的页面上生效 http(s):// 从 localhost, (中文(简体) ), *.localhost, (中文(简体) ), 127.x.x.x 财务报告和审定财务报表 [::1]在已部署的域中,它没有任何作用.
混合应用程序必须关闭它在释放建筑. 电容、电容、 Cordova 和 Tauri 甚至服务于从 localhost。SDK只过滤iOS、macOS和Linux上使用的自定义方案(capacitor://, (中文(简体) ), ionic://, (中文(简体) ), tauri://); Android 和 Windows 构建 (http(s)://localhost, (中文(简体) ), http(s)://tauri.localhost)看起来完全像本地的dev服务器. 如果设置被保留,制作广告要求切换到app-key路径(每个请求都带有CORS预飞).
因为一个混合应用程序的由来是 localhost,服务器将它视为测试模式并服务 仅测试广告,即使与 liveAds 关闭。 Web SDK不支持混合应用中的制作广告提供.
一个不见了 appKey,或属于另一应用程序的密钥,在浏览器控制台上登录警告. 用另一个应用程序的密钥,服务器回答"没有广告".
App-和unit-level request gating(remote-config)在本地主机上没有应用.

目标设定

使用 contextId 能够针对更相关的广告进行背景定位:

await adrop.renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  contextId: 'YOUR_CONTEXT_ID' // Context ID from Adrop Console
});

这个 contextId 匹配您下方的投放控制台中配置的ID 目标菜单 > 目标设定。。。 .

主题支持

SDK为广告支持轻而暗的主题. 您可以使用 data-adrop-theme 属性或属性 theme 选项在 renderAd。。。 .

装入回填广告

在没有直接交易广告时会自动加载回填广告.

说明: 后填充配置必须设置在 Dropp Console 中才能工作 .

当应用程序没有活动时

如果空投控制台报告您的应用程序没有活动活动( 远程配置) active: false),SDK跳过本地的广告请求,直到服务器提供的再检查时间: requestAd 编号 : requestAds 返回时 code: 4001 没有网络电话,和 load() 倒倒倒倒倒地放火 adNoFill (事件与服务器的不填充相同,所以一个页面将自己的倒计时加在 adNoFill 继续工作). 国家被保存在 localStorage['adrop:{appId}:backoff'] (没有识别符)所以它能活下来的页面负载. 预览请求( E)adId永远不会跳过.

当某个特定的广告单位没有东西可以填补时

当应用程序运行时 该单位 完全没有广告, 服务器会给不填充响应附加一个重试时间。 SDK然后只跳过对这个单元的请求直到那个时候,返回 code: 4002 (不填); load() 倒倒倒倒倒地放火 adNoFill 和往常一样其他单位不受影响,广告填充后会立即取消跳出. 它最多持续24小时,当在控制台上增加一个活动时会更快地被解除.

跳跃被缩小到 单位和 contextId 组合. 背景选择可以改变同一单位的现有条件,因此,每个单位 contextId 被分别跟踪,一个屏幕上没有填充,从不阻挡另一个屏幕.

回填渲染模式( 1. 2. 3+)

模式	行为
`responsive` (默认)	后填充提供者根据容器宽度选择大小. SDK 储备a `min-height` 当容器没有明确高度时自动.
`fixed`	将广告延伸至容器高度(`width:100%; height:100%`)—— 1.2.1行为. 用于固定高度周围设计的槽.

// Global default
Adrop.observe({ appId: 'YOUR_APP_ID', backfillMode: 'fixed' });

// Per-slot (HTML)
// <div data-adrop-unit="..." data-adrop-backfill-mode="fixed"></div>

// Per-slot (programmatic)
await adrop.renderAd(container, { unit: 'PUBLIC_xxx', backfillMode: 'fixed' });

见后填充渲染模式指南详细情况.

清除广告

从容器中删除广告 :

const container = document.getElementById('ad-container');
adrop.clear(container);

重新装入广告

在HTML中,您可以通过调用:

const container = document.getElementById('ad-container');
const paramsToOverride = {
    unit: 'NEW_UNIT_ID',
    contextId: 'NEW_CONTEXT_ID',
    theme: 'light'
}
adrop.renderAd(container, paramsToOverride);

// if you don't want to override previous params, just call without second argument
adrop.renderAd(container);

用户名

如果你没准备好 uid,SDK为浏览器创建了匿名ID(ULID),并发送了广告请求,事件和财产更新——因此频率盖和观众目标也同样适用于登录出入口的访客. 身份证是监视你的 appId 并存放在一个地方:

存储	名称	目的	终身
可注册域上的一党饼干(由子域共享)	`adrop_uid_{appId}`	匿名用户ID	400天,每页更新
`localStorage` - 只有在饼干不能写的时候	`adrop:{appId}:uid`	匿名用户ID	直到清除
Cookie (测试)	`adrop_probe`	为上面的 cookie 找到可注册域—— 随机值, 写入后立即删除	立即删除( 60 s 上限)

设定 uid 用于登录用户每页 (单位:千美元)Adrop.observe({ uid }), (中文(简体) ), setConfig({ uid }) 或者说 adrop.uid = ...) (中文(简体) ). 设置它删除匿名ID, 而下一页没有 uid (登录后)开始一个新的。登录的页省略 uid 获得新的匿名身份,这削弱了该页面上的频率封顶.
request.uid 仅覆盖该请求的ID;事件和财产更新继续使用已配置或匿名的ID.
adrop.uid 只返回您设定的值,绝不是匿名身份.
在保留浏览器存储时, 频率封顶会保持。如果两者兼有饼干和 localStorage 被屏蔽,仅当前页面的ID会持续-广告仍在加载. 在浏览器(SSR)外没有创建ID.
appId 需要将匿名身份证保存在页面上;没有匿名身份证,身份证只保存在内存中.
对于匿名访客, metrics.commit() 仅在属性时发送 userDataConsent 实值 true。。。 .

更新用户代号

adrop.uid = 'new-user-id';

配置选项

初始化选项

{
  appId: string;          // Application ID (required)
  uid?: string;           // Logged-in user ID — omit for an anonymous ID (see "User ID")
  appKey?: string;        // Application key
  liveAds?: boolean;      // Serve live ads on localhost when appKey is set (default: unset = test ads)
  debug?: boolean;        // Enable debug logging (default: false)
}

请求选项

{
  unit: string;                   // Ad unit ID (required)
  uid?: string;                   // Override user ID for this request
  contextId?: string;             // Context identifier
  keywords?: string[] | string;   // Keyword targeting (array or comma-separated string)
  trackMode?: number;             // Tracking mode
}

活动

AD_RECEIVED - 自动装入成功
AD_FAILED - 装入失败
AD_NO_FILL - 本请求无广告
AD_BACKFILL_NO_FILL - 没有可用的回填广告
AD_IMPRESSION - 印象记录
AD_CLICKED - 用户点击广告

类型脚本支持

SDK包括框外的TypeScript定义:

import Adrop, { AdropConfig, AdData } from '@adrop/ads-web-sdk';

const config: AdropConfig = {
  appId: 'your-app-id',
  uid: 'user-123',
  debug: true
};

const adrop = Adrop.observe(config);

SPA 支持

对于单页应用程序,在导航时清除以前的广告:

function navigateToNewPage() {
  // Clear existing ads
  const adElements = document.querySelectorAll('[data-adrop-unit]');
  adElements.forEach(element => adrop.clear(element));

  // Load new page content
  loadNewPageContent();
}

许可证

版权2025开放Rhapsody有限公司.

根据Apache许可证第2.0版("License"); 您不得使用此文件,除非符合许可证. 您可在下列地点获得许可证副本:

http://www.apache.org/licenses/LICENSE-2.0

除非适用的法律要求或书面同意,否则软件根据许可证发放的是在“AS IS”BASIS上发放的, 没有任何明示或暗示的警告或条件. 有关许可的特定语言的许可证许可证的限制.

版本与发布记录

@adrop/ads-web-sdk 共发布 25 个版本，首次发布于 2025/12/02；过去 12 个月发布了 25 个版本。

版本	发布日期	距今
`1.4.0`latest	2026/10/19	19 天前
`1.3.0`	2026/10/14	24 天前
`1.2.6`	2026/10/14	24 天前
`1.2.5`	2026/07/03	4 个月前
`1.2.4`	2026/06/25	4 个月前
`1.2.3`	2026/05/26	5 个月前

关于 @adrop/ads-web-sdk 的常见问题

@adrop/ads-web-sdk 是什么？

丢弃 Ads 网络 SDK

如何安装 @adrop/ads-web-sdk？

在项目目录运行 npm install @adrop/ads-web-sdk，或使用 pnpm add / yarn add / bun add。

@adrop/ads-web-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@adrop/ads-web-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@adrop/ads-web-sdk 可以商用吗？

@adrop/ads-web-sdk 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@adrop/ads-web-sdk 的下载量有多少？

根据 npm 官方下载统计，@adrop/ads-web-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,995 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@adrop/ads-web-sdk 还在维护吗？

最新版本 1.4.0 发布于 2026/10/19（19 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2025/12/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @adrop/ads-web-sdk

pnpmpnpm add @adrop/ads-web-sdk
yarnyarn add @adrop/ads-web-sdk
bunbun add @adrop/ads-web-sdk

在你的项目目录中运行此命令。

近 30 天下载

2,995

约 2995 次日均 100 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，2 天前更新

最新版本1.4.0发布于 19 天前

开源许可Apache-2.0宽松许可

包体积244 kB24 个文件 · 解压后

运行依赖0 个零依赖

模块格式ES Module

TypeScript自带类型

发布版本25 个近 12 个月 25 个

首次发布2025/12/0211 个月前

元数据更新2026/10/19

每一个软件包背后，
都有分享与创造的人。

@adrop/ads-web-sdk

丢弃 Ads 网络 SDK

特征

安装

国家预防机制

光盘N

快速启动

1. 初始化SDK

2. 装货封装广告

自动加载( 声明式)

程序加载

3. 装入原生广告

自动装入自定义 UI (声明式)

程序加载自定义 UI

可用的数据投放本地字段

自定义 UI 执行示例

媒体槽( O)extraAssets(中文(简体) )

点击行为控制

4. 事件处理

高级使用

更新属性

正在本地主机上验证 Live Ads

目标设定

主题支持

装入回填广告

当应用程序没有活动时

当某个特定的广告单位没有东西可以填补时

回填渲染模式( 1. 2. 3+)

清除广告

重新装入广告

用户名

更新用户代号

配置选项

初始化选项

请求选项

活动

类型脚本支持

SPA 支持

许可证

版本与发布记录

关于 @adrop/ads-web-sdk 的常见问题

@adrop/ads-web-sdk 是什么？

如何安装 @adrop/ads-web-sdk？

@adrop/ads-web-sdk 支持 TypeScript 吗？

@adrop/ads-web-sdk 支持 ESM 还是 CommonJS？

@adrop/ads-web-sdk 可以商用吗？

@adrop/ads-web-sdk 的下载量有多少？

@adrop/ads-web-sdk 还在维护吗？

媒体槽( O)`extraAssets`(中文(简体) )