# @adrop/ads-web-sdk 中文文档

规范地址：https://npmcn.com/package/%40adrop/ads-web-sdk/

版本：1\.4\.0
npm 元数据更新时间：2026-10-19T05:59:39.482Z
中文译文更新时间：2026-11-06T14:21:43.270Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adrop/ads-web-sdk
原文对照：https://npmcn.com/package/%40adrop/ads-web-sdk/?lang=original
项目主页：https://adrop.io/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：244 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-12-02T06:29:07.837Z
- 最新版本发布：2026-10-19T05:59:39.065Z
- 近 30 天下载量：2995（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

丢弃 Ads 网络 SDK

## 安装

```sh
npm install @adrop/ads-web-sdk
```

也可以使用：`pnpm add @adrop/ads-web-sdk`、`yarn add @adrop/ads-web-sdk`、`bun add @adrop/ads-web-sdk`

## README

# 丢弃 Ads 网络 SDK

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![npm version](https://badge.fury.io/js/%40adrop%2Fads-web-sdk.svg)](https://badge.fury.io/js/%40adrop%2Fads-web-sdk)

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

## 特征

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

## 安装

### 国家预防机制

```bash
npm install @adrop/ads-web-sdk
```

### 光盘N

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

## 快速启动

### 1\. 初始化SDK

```javascript
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的使用:

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

### 2\. 装货封装广告

#### 自动加载( 声明式)

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

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

可选数据属性 :

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

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

#### 程序加载

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

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

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

可选字段 :

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

```javascript
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"`数字 :

```html
<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>
```

整个区域点击功能 :

```html
<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

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

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

整个区域点击功能 :

```javascript
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 执行示例

```html
<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`。 。 。 .

```javascript
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\. 事件处理

听广告生命周期事件:

```javascript
// 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);
});
```

## 高级使用

### 更新属性

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

```javascript
// 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` 与你的 `appKey`SDK然后用应用密钥认证,就像本地SDK一样.

```javascript
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` 能够针对更相关的广告进行背景定位:

```javascript
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行为. 用于固定高度周围设计的槽. |

```javascript
// 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' });
```

见 [后填充渲染模式指南](https://npmcn.com/package/%40adrop/docs/web/backfill_mode_guide.md) 详细情况.

### 清除广告

从容器中删除广告 :

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

### 重新装入广告

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

```javascript
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`。 。 。 .

### 更新用户代号

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

## 配置选项

### 初始化选项

```typescript
{
  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)
}
```

### 请求选项

```typescript
{
  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定义:

```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 支持

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

```javascript
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 是什么？

丢弃 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 和提交记录判断。