# @adhese/sdk 中文文档

规范地址：https://npmcn.com/package/%40adhese/sdk/

版本：1\.13\.2
npm 元数据更新时间：2026-11-05T12:21:20.147Z
中文译文更新时间：2026-11-06T01:57:48.695Z
软件包许可：GPL-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adhese/sdk
原文对照：https://npmcn.com/package/%40adhese/sdk/?lang=original
项目主页：https://github.com/adhese/sdk_typescript#readme
源码仓库：https://github.com/adhese/sdk_typescript

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

- 包体积（解压后）：402 kB，79 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-03-22T09:47:54.566Z
- 最新版本发布：2026-11-05T12:21:19.747Z
- 近 30 天下载量：6835（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：250（近 12 个月 71 个）

## 中文简介

阿德斯 SDK

## 安装

```sh
npm install @adhese/sdk
```

也可以使用：`pnpm add @adhese/sdk`、`yarn add @adhese/sdk`、`bun add @adhese/sdk`

## README

## 安装

### 国家预防机制

您可以使用国家防范机制在项目中安装 SDK :

```bash
npm install @adhese/sdk
```

## 使用量

要使用 SDK, 您需要创建 Adhese 实例, 用您的账户 ID 配置 :

```js
const adhese = createAdhese({
  account: 'your-account-id',
});
```

### 自动在页面上找到槽

SDK可以自动找到页面上的所有槽并加载. 这是最容易开始的方法:

```js
const adhese = createAdhese({
  account: 'your-account-id',
  findDomSlotsOnLoad: true,
});
```

通过查找带有 `adunit` 课。 要件必须具有: `data-format="YOUR_FORMAT"` 属性设置在元素上,以便知道需要获取哪种格式.

示例 DOM 插槽 :

```html
<div class="adunit" data-format="billboard"></div>

```

### 在 DOM 准备好之前获取槽

如果你想在DOM准备好之前取出槽,你可以通过 `initialSlots` 选项 `createAdhese` 函数。 如果您想要尽快启动获取进程, 这一点特别有用 。 下边是 需要事先知道哪个档位会出现在网页上.

```js
const adhese = createAdhese({
  account: 'your-account-id',
  initialSlots: [
    {
      containingElement: 'slot-1', // ID of the element that contains the slot
      format: 'billboard',
    },
    {
      containingElement: 'slot-2', // ID of the element that contains the slot
      format: 'leaderboard',
    },
  ],
});
```

示例 HTML :

```html
<div id="slot-1" class="adunit" data-format="billboard"></div>
<div id="slot-2" class="adunit" data-format="leaderboard"></div>
```

## 选项

这个 `createAdhese` 函数接受以下选项:

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `account`\* 联合国 | `string` | \- 说吧 | 您的 Adhese 账户 ID |
| `host` | `string` | `'https://{{account}}.ads.adhese.eu'` | Adhese API 主机 |
| `poolHost` | `string` | `'https://{{account}}.pool.adhese.eu'` | 阿德塞游泳池主机 |
| `location` | `string` | `window.location.pathname` | 页面位置. 用于确定当前页面位置标识符 . |
| `requestType` | `'GET'` 或者说 `'POST'` | `'POST'` | 用于 Adhese API 请求的请求Ads 类型 。 这也可以是 `GET` 或者说 `POST`。 。 。 . `POST` 是默认的,并且提供了最多的选项. `GET` 比较有限,因为它需要通过数据作为搜索参数,但可以在下列环境中使用: `POST` 不允许提出请求. |
| `debug` | `boolean` | `false` | 启用调试模式 |
| `findDomSlotsOnLoad` | `boolean` | `false` | 自动在页面上找到槽并加载 |
| `parameters` | `Record<string, string, Array<string>>` | `{}` | 附加参数随每项请求一起发送. 确保参数的密钥只包含 `2` 字符键. |
| `consent` | `boolean` | `false` | 用户同意跟踪 |
| `initialSlots` | `Array<Slot>` | `[]` | 在DOM准备好之前要取的槽 |
| `logReferrer` | `boolean` | `true` | 将登录 `document.referrer` 给Adhese API的 `BASE64` 与 `re` 参数. |
| `logUrl` | `boolean` | `true` | 将登录 `location.href` 给Adhese API的 `BASE64` 与 `ur` 参数. |
| `eagerRendering` | `boolean` | `false` | 广告一收到就会制作 总而言之,建议保留这个 `false` 为了更好的表现. |
| `queries` | `Record<string, string>` | `{phone: '(max-width: 768px) and (pointer: coarse)',tablet: '(min-width: 769px) and (max-width: 1024px) and (pointer: coarse)',desktop: '(min-width: 1025px) and (pointer: fine)',}` | 将用于确定设备类型和屏幕大小。 匹配的查询密钥将在 `dt` 财务报告和审定财务报表 `br` 参数. |
| `plugins` | `ReadonlyArray<(context: AdheseContext) => void>` | `[]` | Adhese 实例所用的插件 。 这些插件使用Adhese语境调用,并在Adhese语境初始化期间运行. |

\* 必需

## 常见问题

### @adhese/sdk 是什么？

阿德斯 SDK

### 如何安装 @adhese/sdk？

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

### @adhese/sdk 支持 TypeScript 吗？

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

### @adhese/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @adhese/sdk 可以商用吗？

@adhese/sdk 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @adhese/sdk 的下载量有多少？

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

### @adhese/sdk 还在维护吗？

最新版本 1\.13\.2 发布于 2026/11/05（今天）；至今共发布 250 个版本，其中过去 12 个月发布了 71 个；首次发布于 2024/03/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。