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

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

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

安装

npm install @ada-cx/messaging-sdk

快开始

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

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 如果您想要运行时模块而不启动 部件, 例如在需要部件前预加载 :

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

const sdkModule = await loadMessagingSdk();

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

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 设置.

类型

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

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.

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()。通过 用自己的间谍替换任何方法的覆盖 :

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 。 无效 或无值回落到稳定的推出.

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

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 从默认导入中生成获取失败警告 :

[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 块,请更新您在获取失败警告中显示的宿主策略 .

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

[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,直接为:

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。被钉入的条目将在 您通过的资产主机 .