Track Business SDK

主题外观

历史
文档版本
最新文档2026.11.0✓
AI 文档索引 ↗AI 辅助接入

Web SDK ​

AI 辅助接入 Web

在浏览器中安装 SDK，配置接收地址与项目凭据，记录并验证首个事件。

前置准备 ​

  • 一个可用的 http 或 https 事件接收 endpoint；
  • 与单一项目绑定的公开 projectKey，详见环境与项目凭据；
  • 使用 Vite、Webpack 等构建工具，或通过 Script 标签接入普通网页。

选择接入方式 ​

npm / ESM 安装 ​

步骤 1：安装依赖包 ​

从 Web SDK 下载页下载离线包，解压到项目的 libs/ 目录后安装：

bash
# 安装 Web SDK npm 包
npm install ./libs/track-business-web-sdk-2026.11.0/packages/track-business-sdk-web-1.0.0.tgz

React/Vue 项目可另行安装同版本交付中的框架包，参见React 与 Vue 接入。

步骤 2：创建并启动客户端 ​

在浏览器入口创建 SDK 实例。create() 会开始初始化；如后续逻辑需要确认初始化完成，可等待 ready()：

ts
import { TrackBusinessSDK } from '@track-business/sdk-web';

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
});

// 仅在需要等待初始化结果时调用
await sdk.ready();

SDK 默认以 GRANTED + MINIMAL 启动，无需另调 Consent API；该技术默认值不代替宿主的授权流程。若要求授权前不采集，使用 initialConsent: { status: 'PENDING' }，并在宿主/CMP 确认授权后调用 grantConsent('STANDARD')。详见Consent 与隐私。

页面标题默认不采集；URL 会去掉凭据、查询参数和片段，路径仍可能包含业务标识。启用页面或点击采集前，请按页面隐私配置设置路径模板，或关闭路径与来源页采集。

TIP

SSR / 框架注意点：在 Next.js、Nuxt 或 Vite SSR 中，仅在浏览器环境创建 SDK，例如放入 useEffect、onMounted 或检查 typeof window !== 'undefined'。需要等待初始化时调用 ready()；初始化失败后可调用 init() 重试。

步骤 3：记录首个事件 ​

在业务代码中调用 track() 记录事件。返回表示 SDK 接受了调用；Outbox 持久化和上传是后续异步步骤：

ts
// 记录事件；SDK 按配置调度上传：
sdk.track('quickstart_completed', {
  source: 'web-docs',
});

Script 标签 ​

不使用构建工具的页面可下载浏览器单文件脚本，通过 window.TrackBusinessSDK 创建实例。插件需显式启用。

html
<script src="./track-business-sdk-web-1.0.0.min.js"></script>
<script>
  const sdk = window.TrackBusinessSDK.create({
    endpoint: 'https://collector.example.com/v1/events/batch',
    projectKey: 'web-public-project-key',
  });

  sdk.track('quickstart_completed', { source: 'web-script' });
</script>

请固定脚本版本，与当前使用的 SDK 文档保持一致。

验证交付结果 ​

  1. 使用测试环境的 endpoint 和 projectKey，记录上面的 quickstart_completed 事件。
  2. 在浏览器 Network 中检查上传请求；需要立即尝试发送时，可调用 await sdk.flush()。
  3. 确认响应符合整批 ACK 契约，并核对接收端的事件名和属性。

SDK 会自动合批。flush() 返回或队列为空不能单独证明事件已接收；详见数据校验。

可选：检查待发事件的确认结果 ​

记录测试事件后，可用 verifyDelivery 检查当前待发范围。它不能代替接收端记录。

ts
const report = await sdk.verifyDelivery({ timeoutMs: 3000 });
switch (report.status) {
  case 'acknowledged':
    console.info('当前待发范围已确认');
    break;
  case 'rejected':
    console.info('存在明确拒收，请排查配置或事件规则');
    break;
  case 'empty':
    console.info('当前没有待验证事件，不作为接收证明');
    break;
  default:
    console.info('尚未完整确认', report.reason);
}

各状态含义见数据校验。

可选配置 ​

登录后关联用户 ​

业务系统确认用户登录后再关联业务身份；SDK 不会从 Cookie、请求头或页面内容猜测用户。切换账号使用 switchUser()，安全退出使用 signOut()：

ts
await sdk.identify('user_10086');
sdk.track('account_page_viewed');

// 已知要切换到另一个账号时：
await sdk.switchUser('user_10087');

// 共享设备或需要安全账号边界时：
await sdk.signOut();

identify() 用于首次关联；已有用户时不可用它静默覆盖账号。普通账号切换和退出语义不同，详见身份与生命周期。

页面与生命周期插件组合 ​

createWebBetaClient 会注册页面、生命周期、归因与性能插件，但不会绕过 Consent。该插件组合要求 STANDARD；只有宿主/CMP 已确认相应授权后，才将 Consent 设为 STANDARD：

ts
import { createWebBetaClient } from '@track-business/sdk-web';

const sdk = createWebBetaClient({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  // 仅在宿主/CMP 已确认 STANDARD 级别授权后设置
  initialConsent: { status: 'GRANTED', level: 'STANDARD' },
});
await sdk.ready();

若需要授权前不采集，以 PENDING 初始化，并在宿主/CMP 确认授权后调用 grantConsent('STANDARD')。此期间 Beta 插件不会产生事件。页面 URL 可能包含业务标识时，按页面隐私配置限制路径和来源字段。

NOTE

Beta 配方不包含 DOM 点击、Rage Click、曝光或交互采集。相关能力及目标白名单配置见Web 插件与推荐装配。

跨源上报配置见 Web 跨域与网络配置。