Web SDK

AI 辅助接入 Web

安装 SDK，配置上报地址和项目 Key，然后记录并验证首个事件。

前置准备

• 项目接入信息中的上报地址 endpoint 和项目 Key projectKey；
• Web 构建项目，或可通过 Script 标签加载 SDK 的网页。

---

选择接入方式

npm / ESM 安装

步骤 1：安装依赖包

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

# 安装 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 实例。将示例地址和项目 Key 替换为项目接入信息中的值；直接使用 Track 网关地址时，无需配置站点转发。若站点限制网页可连接的地址，请允许连接该网关域名。

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

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

// 后续代码需要等待初始化完成时调用
await sdk.ready();

SDK 默认按 GRANTED + MINIMAL 运行。若网站要求用户同意后才能采集，请按授权与隐私以 PENDING 初始化；获得授权前不会产生事件。

TIP

Next.js / Nuxt：仅在浏览器环境创建 SDK，例如使用 useEffect、onMounted 或检查 typeof window !== 'undefined'。

步骤 3：记录首个事件

在业务代码中调用 track() 记录事件。SDK 随后安排上传：

sdk.track('quickstart_completed', {
  source: 'web-docs',
});

Script 标签

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

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

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

请使用与交付包相同版本的脚本。

---

验证交付结果

1. 使用测试环境的上报地址和项目 Key，记录上面的 quickstart_completed 事件。
2. 在浏览器开发者工具的网络面板检查上传请求；需要立即尝试发送时，可调用 await sdk.flush()。
3. 在接收端核对事件名称和属性，并确认响应符合整批 ACK 契约。

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

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

记录测试事件后，可用 verifyDelivery 检查待发事件的确认状态。最终仍需在接收端核对事件。

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()：

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

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

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

identify() 用于首次关联；切换账号和退出的区别见身份与生命周期。

页面与生命周期插件组合

createWebBetaClient 会启用页面、生命周期、归因和性能采集。使用这些功能前，请确认用户已同意相应的数据采集，并将授权级别设为 STANDARD：

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

const sdk = createWebBetaClient({
  endpoint: 'https://gateway.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  // 仅在用户已同意相应采集后设置
  initialConsent: { status: 'GRANTED', level: 'STANDARD' },
});
await sdk.ready();

若需要用户同意后再采集，以 PENDING 初始化，并在获得授权后调用 grantConsent('STANDARD')。启用页面采集前，按页面隐私配置检查路径和来源字段。

NOTE

此组合不包含点击和曝光采集；如需启用，参见Web 插件。

可选：通过网站同源代理上报

若网站需要自行转发事件，将 endpoint 设为网站的同源地址：

endpoint: `${location.origin}/tracking/v1/events/batch`,

将以下配置加入网站的 HTTPS Nginx server：

location = /tracking/v1/events/batch {
    client_max_body_size 2m;
    # 避免将请求 URL 写入访问日志。
    access_log off;
    # 替换为项目接入信息中的上报网关地址。
    proxy_pass https://gateway.example.com/v1/events/batch;
    # 校验网关的 HTTPS 证书；CA 文件路径以服务器实际位置为准。
    proxy_ssl_server_name on;
    proxy_ssl_verify on;
    proxy_ssl_verify_depth 3;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_set_header Host $proxy_host;
    # 不转发网站登录凭据，也不让网关设置网站 Cookie。
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_set_header Proxy-Authorization "";
    proxy_hide_header Set-Cookie;
}

部署前运行 nginx -t；部署后发送测试事件，确认接收端收到事件。此代理只处理事件上报，不转发网站的 Cookie 或认证头。其他 SDK 接口如需使用，应分别配置转发路径。