# @ada-cx/messaging-sdk 中文文档

规范地址：https://npmcn.com/package/%40ada-cx/messaging-sdk/

版本：1\.10\.1
npm 元数据更新时间：2026-11-05T20:26:32.488Z
中文译文更新时间：2026-11-05T21:25:54.477Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40ada-cx/messaging-sdk
原文对照：https://npmcn.com/package/%40ada-cx/messaging-sdk/?lang=original
项目主页：https://docs.ada.cx/

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

- 包体积（解压后）：414 kB，79 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-23T18:33:56.357Z
- 最新版本发布：2026-11-05T20:26:32.294Z
- 近 30 天下载量：18388（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

TypeScript类型,测试模拟,以及Ada Messaging SDK的薄的CDN加载器. 运行时间总是从Ada的CDN中解析出,从未被捆绑在这个包中.

## 安装

```sh
npm install @ada-cx/messaging-sdk
```

也可以使用：`pnpm add @ada-cx/messaging-sdk`、`yarn add @ada-cx/messaging-sdk`、`bun add @ada-cx/messaging-sdk`

## README

# @ada-cx/ message-sdk (英语)

TypeScript类型,测试模拟,以及Ada Message SDK的薄载器.

此软件包从未包含 SDK 运行时间 。 装入器导入运行时间 从Ada的CDN 在页面载荷。 Ada船运行时间修正CDN,和每 页面在下一个负载上接收它们。 这个模式和 `@stripe/stripe-js`。 。 。 .

## 安装

```sh
npm install @ada-cx/messaging-sdk
```

## 快开始

打电话 `loadAdaMessaging` 用你的机器人手柄。 它装入运行时间, 创建 消息接口,启动部件,并返回接口.

```ts
import { loadAdaMessaging } from "@ada-cx/messaging-sdk";

// Module scope: your code holds the only reference.
const ada = await loadAdaMessaging({ handle: "my-bot" });
```

`loadAdaMessaging` 从未将接口指定为 `window` 或任何其他 全球。 将返回的引用保留在模块范围中, 只有您自己的代码 可以到达它。 页面上的每个脚本都可以达到一个全局. 这个 `createAdaEmbedInterface` 导出仅作为遗留存在 `window.adaEmbed` 从脚本- tag 设置迁移的页面的相容外观 .

使用 `loadMessagingSdk` 如果您想要运行时模块而不启动 部件, 例如在需要部件前预加载 :

```ts
import { loadMessagingSdk } from "@ada-cx/messaging-sdk";

const sdkModule = await loadMessagingSdk();
```

`loadMessagingSdk` 提醒飞行中的导入。 同时通话 分享一个 装入。 两个装入器都拒绝装入失败的装入 `MessagingSdkLoadError` 财务报告和审定财务报表 允许重试 :

```ts
import { MessagingSdkLoadError } from "@ada-cx/messaging-sdk";

try {
    await loadAdaMessaging({ handle: "my-bot" });
} catch (error) {
    if (error instanceof MessagingSdkLoadError) {
        console.error(error.code); // "invalid_cdn_base" | "invalid_build_sha" | "unstamped_build_sha" | "sdk_import_failed" | "sdk_module_invalid"
    }
}
```

如果两种进口都失败, `cause` 保存默认根输入出错并只读 `fallbackCause` 保留倒数键入错误. 两个出错都保留了原来的原因链. 无效后退模块使用相同的错误属性并保存 `sdk_module_invalid` 和倒置错误消息.

## 每页一个部件

只有一个消息界面可以在页面上运行,而且 `loadAdaMessaging` 执行这个为你。 屡次打来回相同的回忆承诺 解析到同一起始界面。 第一个呼叫的设置获胜,并且 后来的呼叫从不启动第二个部件. 当后来的电话传来不同的时候 设置,加载器记录一个控制台警告并忽略新的设置. 因此,电话在不止一次的代码中是安全的,例如React 严格模式发展效果. 你不需要缓存承诺 你自己来.

一个失败的负载或开始清除备忘,所以以后的调用可以重试.

通过返回的接口控制部件生命周期 . `ada.stop()` 将部件撕下,然后 `ada.start(settings)` 同样的 界面再次启动。 A 类 `loadAdaMessaging` 后调用 `stop()` 返回时 相同的停止接口。 它不会重新启动部件 。 装入器日志 当返回已停止的接口时, 控制台警告, 所以打电话 `start(settings)` 在界面上再次运行部件.

## 模块格式

一揽子船舶无害环境管理和共同JS都是两个条目的组成部分。 弹药和 无害环境管理运行时间使用 `import` 条件。 捷运和其他通用JS跑车 使用该 `require` 条件。 TypeScript 解析两个条目 `moduleResolution` `bundler`, (中文(简体) ), `node16`和遗产 `node10` 设置.

## 类型

直接导入任何公共类型 。 类型导入添加了零运行时间代码.

```ts
import type {
    AdaMessagingInterface,
    AdaMessagingSettings,
    AdaMessagingStartOptions,
    PublicMessage,
    ResetParams,
} from "@ada-cx/messaging-sdk";
```

`AdaMessagingInterface` 是接口 `loadAdaMessaging` 决定。 这个 `AdaEmbedInterface` 名称仍可用作其别名.

运行时符号, 如 `AdaMessagingClient` 财务报告和审定财务报表 `createAdaEmbedInterface` 仅作为类型导出。 从 `loadMessagingSdk()`。 。 。 . `createAdaEmbedInterface` 用于从 遗产 `window.adaEmbed` 合同;使用新的整合 `loadAdaMessaging`。 。 。 .

`window.adaSettings`, (中文(简体) ), `new AdaMessagingClient(config)`, (中文(简体) ), `createAdaEmbedInterface(initialSettings)`,以及 `adaEmbed.start(settings)` 接受 `crossWindowPersistence` 作为布尔或 `{ enabled: boolean }`。 。 。 . SDK 使用布尔值 : `enabled`这样 `{ enabled: false }` 禁用持久性. 对于无效值,SDK记录每页负载一次控制台警告.

无效的覆盖保留保留主机设置或 `window.adaSettings` 倒计时. 无效的构造值保存 `window.adaSettings` 倒计时. 没有设置, 持久性默认继续 . 类型脚本设置尚存 `boolean`。 。 。 .

## 测试您的整合

这个 `./testing` 条目提供了消息界面的内存模拟. 你的单位测试从不碰CDN.

```ts
import { createMockAdaMessaging } from "@ada-cx/messaging-sdk/testing";

const ada = createMockAdaMessaging();

await ada.sendMessage("hello");
expect(ada.calls).toContainEqual({
    method: "sendMessage",
    args: ["hello"],
});

// Simulate an SDK event for your subscribers.
await ada.subscribeEvent("ada:conversation:message", onMessage);
ada.$emit("ada:conversation:message", { message_id: "m1" });
```

模拟记录每一次通话 `calls`。它保持光状态:已发送信件 显示在 `getMessages()`,以及 `open`编号 :`close` 驱动 `isOpen()`。通过 用自己的间谍替换任何方法的覆盖 :

```ts
const ada = createMockAdaMessaging({ getMessages: vi.fn(async () => []) });
```

## 纸条

装入器以全动态的 URL 导入运行时间 。 导入是 附加说明 `/* webpackIgnore: true */` 财务报告和审定财务报表 `/* @vite-ignore */`这样 webpack和Vite留给浏览器解决. 不复制导入 输入自己的代码,没有这些说明。 如果你的捆绑者仍然重写 动态导入,配置以忽略导入 `https:` URLs (英语).

## 版本和中继验证

Npm版本只涵盖加载器,类型,和模拟. 从来没有 锁定运行时间。 运行时间总是从Ada的CDN推出中解析出 装入.

要验证任何页面上的特定运行时间,请添加 `?ada-messaging-version=<version>` 查询参数到页面 URL。 数值 接受一个 `pr-<N>` 预览构建或主构建的 git SHA 。 无效 或无值回落到稳定的推出.

要对不同的资产主机进行验证,将其根传递给加载器. 阿达 当您安排生产前验证时, 给出主机值 :

```ts
await loadAdaMessaging(
    { handle: "my-bot" },
    { cdnBase: "<ada-provided-asset-host>" },
);
```

首选生产根是 `https://messaging-assets.ada.support/`。 。 。 . CSP已经允许的制作页面 `static.ada.support`,使用时 `cdnBase: "https://static.ada.support/messaging/"`。 。 。 . 支持生产根的套件输出为 `FALLBACK_MESSAGING_CDN_BASE`。 。 。 .

无 `cdnBase`,加载器从静态根自动重试一次 当默认导入失败时, 包括 CSP 和网络失败 . 如果默认的靴子在显示失败或运行时间失败后拒绝, 它会驱逐其共享 `window.__AdaMessagingSdkBootstrap` 答应. 静态的靴子可以独立解决. 如果解决方案尚未解决或已成功,将分享承诺. 重试保存 `pinBuildSha` 联 合 国 `<sha>/sdk/index.js` 路径. 成功的无钉倒置使用静态根来进行显示和帧. 明确 `cdnBase` 禁用自动倒置. 模块无效和验证错误保留其原始代码和消息. 如果两种进口都失败, `sdk_import_failed` 两个尝试的 URL 名称.

在成功倒计时后,加载器记录每页1个警告,不进行调试记录. 警告包括原出错作为其第二个控制台参数. A 类 `TypeError` 从默认导入中生成获取失败警告 :

```text
[Ada] Loaded the Messaging SDK from https://static.ada.support/messaging/ because the default root https://messaging-assets.ada.support/ was blocked or unavailable. Add https://messaging-assets.ada.support to script-src, connect-src and frame-src, or pass cdnBase: "https://static.ada.support/messaging/".
```

对于 CSP 块,请更新您在获取失败警告中显示的宿主策略 .

其他错误产生评估失败警告:

```text
[Ada] Loaded the Messaging SDK from https://static.ada.support/messaging/ because the module at https://messaging-assets.ada.support/sdk.js failed to evaluate (Error: boom). This is an Ada-side problem, not your host's CSP. Report it to Ada.
```

对于评估失败的警告,将原错误报告给Ada. 网络失败也会产生取出失败的警告 . 丢出模块 `TypeError` 评估期间还生成取出失败警告,因此分类不能证明是CSP块.

从请求的根成功加载不会产生回落警告 .

### 将 CDN 构建

软件包导出 `CDN_BUILD_SHA`。值是 Git 承诺的 SHA 这个 npm 版本发布 。 阿达各部署 承诺的运行时间 在一个不可改变的SHA根 在CDN。 因此,价值 命名与 npm 版本相关的 CDN 构建 .

传SHA作为 `pinBuildSha` 装填器选项 。 装填器然后跳过 推出靴子和进口 建立不可改变的入口, `<cdnBase>/<sha>/sdk/index.js`,直接为:

```ts
import {
    CDN_BUILD_SHA,
    isCdnBuildShaStamped,
    loadAdaMessaging,
} from "@ada-cx/messaging-sdk";

if (isCdnBuildShaStamped()) {
    await loadAdaMessaging({ handle: "my-bot" }, { pinBuildSha: CDN_BUILD_SHA });
}
```

**不建议生产平宁.** 一个被钉住的跑步时间错过了Ada的 修复和推出。 被绑定的运行时间也可以在后来的服务器合同之前 改变并停止工作。 使用 Pin 只调试一个问题, 验证一个 或根据已知的运行时间复制报告.

该选项接受任何部署主机的全40个特性的六分法 建设。 装载器拒绝带有下列值的任何其他值: `invalid_build_sha` 错误 代码。 只有已出版的软件包携带着真实的SHA. 在存储器中 本地制作的副本, `CDN_BUILD_SHA` 是一个40-零的占位符,并且 `isCdnBuildShaStamped()` 返回时 `false`。装载器拒绝占位符 与 `unstamped_build_sha` 错误代码 .

Npm 发布和CDN 部署相同承诺平行运行. 单位 在发布后的第几分钟, 针头可以失败 `sdk_import_failed` 直到部署完成 如果部署失败 建造从不存在。 在这两种情况下,无担保的违约都不受影响.

`pinBuildSha` 编曲: `cdnBase`。被钉入的条目将在 您通过的资产主机 .

## 常见问题

### @ada-cx/messaging-sdk 是什么？

TypeScript类型,测试模拟,以及Ada Messaging SDK的薄的CDN加载器\. 运行时间总是从Ada的CDN中解析出,从未被捆绑在这个包中\.

### 如何安装 @ada-cx/messaging-sdk？

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

### @ada-cx/messaging-sdk 支持 TypeScript 吗？

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

### @ada-cx/messaging-sdk 支持 ESM 还是 CommonJS？

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

### @ada-cx/messaging-sdk 可以商用吗？

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

### @ada-cx/messaging-sdk 的下载量有多少？

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

### @ada-cx/messaging-sdk 还在维护吗？

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