# @adtention/sdk 中文文档

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

版本：0\.4\.0
npm 元数据更新时间：2026-06-30T16:52:53.691Z
中文译文更新时间：2026-11-06T16:31:26.525Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：77.8 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-06-17T19:01:03.762Z
- 最新版本发布：2026-06-29T20:14:54.061Z
- 近 30 天下载量：2738（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

发布者SDK for Adwenty ——在您的应用程序的等待状态中显示一行赞助线并赚取回购. 终端安全,一能,多租户.

## 安装

```sh
npm install @adtention/sdk
```

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

## README

# @ audent/ sdk (中文(简体) )

发布器 SDK 用于 [预 留](https://adtention.ai/integrate)显示 **一行赞助** 在你的应用软件 等待状态(编码代理状态行、 CLI 旋转器、 终端闲置时刻) 转相. 赞助行为正文. 只有分类标签和不透明的每个用户代号才会离开你 进程.

-   **终端安全.** 在你看到它之前, 赞助者文本被删除 ANSI 和控制字节. 没有逃生注射,没有木材注射.
-   **同上,注:.** 每一份服务都带有"非ce",所以复试从不重复计算.
-   **多地租户.** 一个出版商帐户,许多终端用户,每个收费限额都是独立的.
-   **通论.** 核心仅使用 `fetch` 和Web Crypto, 因此它运行在 Cloudflare 20+节点上 工人,德诺,邦,和浏览器。 用于节点生活的文件支持身份商店 `@adtention/sdk/node`。 。 。 .

```bash
npm install @adtention/sdk
```

## 挣钱的两种方法

您选择谁收集 revshare:

-   **你留着它(默认).** 你的项目有一个 `publisher_id`,并显示所有 您的用户贷记这个账户。 这是最整齐者的工作, 和它的其余部分 本指南假定.
-   **你把它传给你的用户.** 该工具单独注册一个 `publisher_id` 每个安装,所以每个 用户收集自己的revshare。 这是Adhead状态行插件使用的模型. 见 [备选模式](https://npmcn.com/package/%40adtention/sdk/#readme-alternative-model-let-each-user-earn-for-themselves)。 。 。 .

## 这是给谁的

你是一个 **开发工具**: CLI,编辑器扩展,终端,编码代理,OSS 项目。 您想要显示赞助行到 __ 用户并赚取回购 项目赚取,而不是最终用户). 你报名了 **一次** 接收 `publisher_id`,并显示每个赞助行 所有用户都记入你的账户.

有两个形状,SDK的手柄都:

|  | **服务器支持的应用程序** | **本地安装的工具** |
| --- | --- | --- |
| 譬如说. | 主机代理, 网络 IDE, SaaS dev 工具 | CLI,编辑器扩展名,终端 |
| 身份 | 你的后端有一个 `publisher_id` | 嵌入您的 **公开** `publisher_id` 在建筑物中 |
| 谁是 `subject` | 每个终端用户( 刷取其用户 id) | 每个安装/机器(随机存储的id) |
| 页:1 `secret` | 留在后端内 | 留在你身边,只用来撤退 |

> **`publisher_id` 是公开的, `secret` 这是私人的.** 服务赞助线路只需要 `publisher_id`这样 可以在分布式二进制或OSS回放中运输安全. 这个 `secret` 仅用于约束 支付目的地和退出, 所以不要在任何你分发.

## 获取一个出版商账户

在你服役之前 你需要一个 `publisher_id`在 [取消门户](https://adtention.ai/onboard): 您选择工具的客户名, 然后它 给你的 `publisher_id` 还有你的付款安排 客户端名称与您的 `publisher_id` 服务器侧并用来卷起你的流量——你从不通过代码. 这是 (单位:千美元) **一次性** 台阶给你。 您的终端用户从未注册 .

然后把它接入:

-   **主机应用程序 :** 设置 `publisherId` 在您的后端内( 例如) . `ADTENTION_PUBLISHER_ID`) (中文(简体) ).
-   **分布式工具 :** 内嵌 `publisherId` 作为公众常数 在你的建筑.

> **提供与服务分开.** 创建账户是门户网站的一次性步骤. 这件事你 _部署_ 应只服务:通过 `serveOnly: true` 所以,它需要提供 `publisherId` 永远不能打电话 `register()`。它使账户创建在一个地方,所以 嵌入不会创建一个流出账户.
> 
> ```ts
> const slot = new SponsorSlot({ publisherId: 'pub_your_id', serveOnly: true, category: 'devops' });
> ```

为了得到报酬,在出入口中加入一个付费目的地,一旦超过10元门槛就退出.

## 快开始

### 高级: 您等待状态中的赞助站

`SponsorSlot` 是高级路径。 每个终端用户的费率限制( 这样您就可以调用每个 转换),缓存最后一个已执行的赞助行,并且从不扔入您的UI.

```ts
import { SponsorSlot, hashSubject } from '@adtention/sdk';

const slot = new SponsorSlot({
  publisherId: 'pub_your_id',   // your earning account (public)
  category: 'devops',           // your app's niche; omit for 'general'
});

// In your render loop / wait state, per end user:
const subject = await hashSubject(currentUserId); // opaque, PII-free
const ad = await slot.next({ subject });
if (ad) {
  render(`${ad.text}  -> ${ad.clickUrl}`); // ad.text is already terminal-safe
}
```

`slot.next()` 每15s只点击一次网络 `subject` (服务器的住址窗口). 单位 返回缓存行。 瞬间出错返回上一个广告( 或 `null`永远不要扔.

### 低级别: 输入客户端

`AdtentionClient` 是一个薄而打字的包装器, 覆盖 V1 API , 当您需要完全控制时 .

```ts
import { AdtentionClient } from '@adtention/sdk';

const client = new AdtentionClient({ publisherId: 'pub_your_id' });

const ad = await client.serve({ category: 'web', subject });
// ad.text is sanitized; ad.clickUrl is absolute and http(s)-only
console.log(ad.text, ad.billable, ad.credit);

// Record a click (engagement only, never billed) and get the destination to open:
const dest = await client.recordClick(ad.impressionId);

// Check earnings (account-level: the project's running balance, for your own dashboard):
const bal = await client.balance();
console.log(bal.balanceUsd, bal.payable);
```

### 分布式CLI/扩展(项目收入)

和上面一样,但是 `publisher_id` 是一个公众常年烤入你的建筑, 每一个 安装获得稳定的随机 `subject` 因此用户是独立限制费率的. 所有信用池 进入你的账户.

```ts
import { SponsorSlot } from '@adtention/sdk';

const ADTENTION_PUBLISHER_ID = 'pub_your_id'; // public, safe to commit/ship

const slot = new SponsorSlot({ publisherId: ADTENTION_PUBLISHER_ID, category: 'devops' });
const subject = getOrCreateMachineId(); // a random id you persist once per install (e.g. crypto.randomUUID)
const ad = await slot.next({ subject });
if (ad) console.log(ad.text);
```

## 备选模式:让每个用户自己挣钱

最重要的是,这些模型 **你们** (项目)挣取。 如果你愿意的话 **每个终端用户** 赚取收入 让工具自动注册 a _单独_ `publisher_id` 每个安装并持续。 在节点上,使用文件备份商店:插槽 如果服务器忘记了账户,则自动修复。 给你 **没有** 通过一个 `subject`,因为每个安装已经是自己的出版商.

```ts
import { SponsorSlot } from '@adtention/sdk';
import { FileIdentityStore } from '@adtention/sdk/node';
import { homedir } from 'node:os';
import { join } from 'node:path';

const slot = new SponsorSlot({
  identityStore: new FileIdentityStore(join(homedir(), '.myapp', 'adtention.json')),
  category: 'systems',
  ref: process.env.MYAPP_ADTENTION_REF, // optional referral code, attributed on first register
});

const ad = await slot.next(); // no subject: this install IS the publisher
```

> 自我登记(和自我康复)只在下列情况下发生: `identityStore`。如果你通过一个 已固定 `publisherId`SDK从来不会默默地铸造一个新账户 否则会把你孤儿 收入.

## 类别

6个类别是目标网。 导入类型, 您的编辑器自动完成值 :

```ts
import type { Category } from '@adtention/sdk';
// 'web3' | 'web' | 'devops' | 'data' | 'systems' | 'general'
```

无需设置类别 :

-   **无所事事.** 默认为 `general`,它总是通过宽/运行的网络广告填充. 你个 还在挣钱.
-   **设一回.** 大多数工具都有固定的优势(团结工具总是) `web3`) (中文(简体) ). 一行经.
-   **将您已有的文本分类 .** 可选 `classify()` 财务报告和审定财务报表 `classifyFiles()` 帮助端口 引用客户端的关键字/文件休眠并完全运行在您一边:

```ts
import { classify, classifyFiles } from '@adtention/sdk';
classify('we set up docker and a ci/cd pipeline');     // 'devops'
classifyFiles(['foundry.toml', 'package.json']);       // 'web3'  (priority order)
```

正确分类能赚更多钱(目标竞选竞价更高).

## `subject`: 最终用户范围界定

通过不透明 `subject` 因此,服务器可瞄准其费率限制(最多一次可计费印象) 每~15s,加一日封顶) **每个最终用户** 而不是每个账户。 没有它,所有的用户 共享一个全账户限制,对于一个单一用户的 CLI 来说是罚款,但对于一个有多个应用程序来说是破损的 用户.

-   来呀 **不透明**: 随机的每个安装代号, 或 `hashSubject(userId)`从来没有生的PII.
-   来呀 **每个用户稳定** 财务报告和审定财务报表 **区分用户**。 。 。 .
-   `hashSubject(raw, { salt: 'my-app' })` 让同一用户无法在应用程序中操作.

每个科目的功劳都归你 `publisher_id`。 。 。 .

## 剩下的过程

每个服务: `publisher_id`,则 `category` 标签,不透明 `subject`,则a `nonce`就这样 从不 代码、文件内容、及时文本、路径、检索名称或记录誊本.

## API 参考

### `new AdtentionClient(options)`

`{ publisherId?, secret?, serveOnly?, apiBase?, timeoutMs?, fetch? }`。 。 。 . `apiBase` 默认为 `https://api.adtention.ai`。 。 。 .

-   `serveOnly`: 锁定客户端仅服务. 需要一个 `publisherId` (无一出)和 制造 `register()` 掷出. 用在分布的嵌入器中 `publisherId` 拨取 带,因此嵌入式无法创建新账户.
    
-   `register({ ref?, kind? })` 返回时 `{ publisherId, secret, referralCode }` 并采用该身份.
    
-   `serve({ category?, subject?, nonce? })` 返回 a `ServeResult` (卫生) `text`绝对值 `clickUrl`, (中文(简体) ), `billable`, (中文(简体) ), `credit`, (中文(简体) ), `dedup`) (中文(简体) ).
    
-   `balance(publisherId?)` 返回 a `BalanceResult` (账户一级收益,项目本身) 仪表板,不是最终用户渲染.
    
-   `recordClick(impressionId)` 返回目标 URL为 `string | null` (节点/CLI;a) 浏览器,导航到 `ad.clickUrl` 直接让浏览器跟随302.
    
-   `resolveClickUrl(clickUrl)` 返回绝对 http(s) URL 或 `null`。 。 。 .
    
-   `bind(destination, secret?)` 财务报告和审定财务报表 `payout(kind?, secret?)` 是管理层的电话 需要这个秘密.
    

### `new SponsorSlot(options)`

`AdtentionClient` 选项(包括 `serveOnly`+) 加上 (中文(简体) ) `{ client?, category?, dwellMs?, cacheMax?, identityStore?, ref?, onError? }`。 。 。 . `serveOnly` 财务报告和审定财务报表 `identityStore` 彼此之间 独家:如果两者都设定,则施工投出.

-   `next({ subject?, category? })` 返回时 `Sponsor | null` (井有条,缓存,从不掷出.
-   `current(subject?)` 返回最后一个 `Sponsor` 从缓存.
-   `api` 基础是 `AdtentionClient`。 。 。 .

### 帮助者

`getSponsorLine(opts)`, (中文(简体) ), `classify(text)`, (中文(简体) ), `classifyFiles(names)`, (中文(简体) ), `hashSubject(raw, opts?)`, (中文(简体) ), `newNonce()`, (中文(简体) ), `sanitizeAd(s)`, (中文(简体) ), `stripAnsi(s)`, (中文(简体) ), `visibleWidth(s)`, (中文(简体) ), `CATEGORIES`, (中文(简体) ), `isCategory(v)`。 。 。 . 错误显示为 `AdtentionError` (单位:千美元)`.code`, (中文(简体) ), `.status`, (中文(简体) ), `.isNoInventory`, (中文(简体) ), `.isUnknownPublisher`) (中文(简体) ).

## 许可证

麻省理工学院

## 常见问题

### @adtention/sdk 是什么？

发布者SDK for Adwenty ——在您的应用程序的等待状态中显示一行赞助线并赚取回购\. 终端安全,一能,多租户\.

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

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

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

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

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

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

### @adtention/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

@adtention/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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