Web 基础 API

const sdk = TrackBusinessSDK.create({ endpoint, projectKey });
await sdk.ready();
sdk.track('checkout_started');
await sdk.identify('user_1001');
sdk.screen('Checkout');

Web SDK 提供事件记录、身份管理、授权控制和队列上报。

TIP

下载离线包与单文件脚本，请访问 Web SDK 下载。安装步骤见 Web 快速接入。

常用接口

模块类别	核心入口 (TypeScript)	核心入口说明
基础初始化	`TrackBusinessSDK.create(...)`	立即返回实例；需确认初始化结果时调用 `ready()`
业务埋点	`sdk.track(...)` / `sdk.page(...)`	提交采集命令；调用返回不代表已持久化或收到 ACK
位置快照	`sdk.trackWithLocation(...)` / `grantLocationConsent()` / `revokeLocationConsent()`	宿主授权后给单事件附位置；完整语义
手动 Flush	`await sdk.flush()`	请求执行一次队列上传；完成不代表 Collector 已确认
身份管理	`identify` / `clearUser` / `switchUser` / `signOut`	首次关联、清除用户、切换账号、安全退出
身份快照	`sdk.getIdentity()`	获取当前身份快照
用户属性	`sdk.setUserProperties(...)` / `profileIncrement(...)`	提交 Profile / Item 操作事件；接收端执行语义由部署实现决定
元素曝光	`sdk.recordExposure(...)`	标准化 `$sdk_exposure` 事件
健康诊断	`sdk.getHealthSnapshot()` / `exportDiagnostics()`	运行时健康与诊断报告；报告包含有限关联元数据，分享前需检查

create() 会立即返回实例，本地初始化在后台完成。需要确认初始化结果时调用 await sdk.ready()。默认授权为 GRANTED + MINIMAL；若设置 initialConsent: { status: 'PENDING' }，同意前不会记录事件。停止使用时调用 await sdk.destroy()。

多域名与 AMP 接入 API

以下为按需导入的可选能力，使用前请确认所用 SDK 包支持对应模块。首次接入建议先阅读步骤指南。

API	用途	接入说明

两个关联插件均通过创建配置的 siteLinker 安装，同一实例只能选择其中一种。配置和使用步骤见对应指南。

1. SDK 初始化与配置

基础工厂初始化 (`TrackBusinessSDK.create`)

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

初始化参数

下表列出接入时常用的参数。完整字段定义见包内 WebAnalyticsConfig 类型。

配置参数	类型	必填	默认值	说明
`endpoint`	`string`	是	—	Collector 数据接收网关地址
`projectKey`	`string`	是	—	项目公开凭据
`storageNamespace`	`string`	否	按项目配置派生	可选附加作用域；默认绑定 endpoint/projectKey，变更任一项即使用新存储空间
`plugins`	`Plugin[]`	否	`[]`	官方或自定义扩展插件
`autoPage`	`boolean \| string`	否	`false`	`true/'history'` 自动监听路由；`'manual'` 手动控制
`initialConsent`	`ConsentDecision`	否	`GRANTED + MINIMAL`	初始授权状态；严格模式请设为 `PENDING`
`flushAt`	`number`	否	`20`	触发自动批量上报的本地队列条数阈值
`flushIntervalSeconds`	`number`	否	`30`	前台定时合批上报周期（秒）；`0` 关闭前台定时器
`autocapture`	`WebAutocaptureOptions`	否	`undefined`	显式组合页面、生命周期、表单、下载等有界采集；点击采集需配置选择器 allowlist
`debug`	`boolean`	否	`false`	启用 SDK 调试日志；不得用于输出凭据、原始 PII 或完整事件正文
`beforeSend`	`BeforeSendHook`	否	`undefined`	事件发送前拦截、丰富或丢弃钩子
`pagePrivacy`	`WebPagePrivacyOptions`	否	标题关闭、路径/来源开启	页面字段的标题、路径和来源控制；配置说明

本地 Tracking Plan、远程策略和调试面板等可选配置，请按需查看包内类型及对应功能指南。

页面等自动采集 (`createWebBetaClient`)

需要页面、生命周期、归因和性能插件时，可使用 createWebBetaClient。这些插件要求 STANDARD 授权；只有宿主已取得相应授权，才设置 initialConsent: { status: 'GRANTED', level: 'STANDARD' }：

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

需要先取得授权时，设置 initialConsent: { status: 'PENDING' }；PENDING 期间插件不会产生事件。授权后调用 await sdk.grantConsent('STANDARD')。页面地址的处理见页面隐私配置。

可选集成配置

配置参数	类型	必填	默认值	说明
`identityGateway`	`IdentityGateway \| null`	否	`undefined`（关闭）	显式注入身份同步适配器；省略时只使用本地身份，不请求 `/v1/identity/sync`
`hybridBridge`	`TrackBusinessNativeBridge \| false`	否	`false`	显式注入的 Native 容器桥接对象（不自动嗅探全局对象）

2. 身份识别与生命周期

使用以下方法记录用户登录、切换和退出时的身份变化。

方法	触发标准事件	行为语义与说明
`identify(userId)`	`$identity_login`	绑定业务用户主标识并保留当前匿名 ID；用户属性使用 Profile API
`clearUser()`	`$identity_user_cleared`	清除业务主身份作用域，恢复匿名状态
`signOut()`	`$identity_sign_out`	安全退出，清除主身份并强制轮转匿名代际与 Session
`switchUser(userId)`	`$reset` → `$identity_login`	切换不同账号；直接对不同 `userId` 调用 `identify` 将抛出异常
`reset()`	`$reset`	重置 SDK 匿名代际，清空所有外部绑定与 Session 状态
`bindIdentity(namespace, value)`	`$identity_bind`	绑定经过业务与数据治理批准的次级标识；需按原始数据敏感性处理
`alias(aliasId)`	`$alias`	建立别名映射关系，不变更当前主身份
`group(groupId, traits?)`	`$group`	设置 group 标识与属性；不等同于租户隔离或授权边界
`getIdentity()`	—	返回内存中完整的当前身份状态快照

$identity_login 只记录客户端显式绑定事实；后端是否合并匿名历史由接收端决定，具体规则以部署环境的身份策略为准。

// 登录
await sdk.identify('user_10086');
await sdk.setUserProperties({ plan: 'enterprise' });

// 登出
await sdk.signOut();

// 切换账号
await sdk.switchUser('user_10087');

多个页面同时修改身份时，调用可能返回 IDENTITY_STATE_CONFLICT。请读取当前身份并根据实际登录状态决定是否重试。IDENTITY_STORAGE_UNAVAILABLE 表示身份未成功保存；请处理 Promise 拒绝并检查诊断信息。已排队事件仍保留创建时的身份。

3. 事件采集

// 1. 业务自定义埋点：提交采集命令；检查本地诊断确认存储状态
sdk.track('order_completed', {
  order_id: 'ORDER_2026_09001',
  revenue: 299.0,
  currency: 'CNY',
});

// 2. 页面浏览事件：生成标准 $pageview 事件
sdk.page({
  title: '商品详情页',
  category: 'electronics',
});

需要确认页面是否通过治理并写入本地队列时，可使用以下接口：

await sdk.ready();
const result = await sdk.pageWithResult({ routeTemplate: '/products/:id' });
// result.status: stored | rejected | failed

stored 表示事件已写入当前队列，不代表服务端已接收；rejected 表示未通过准入，failed 表示采集或存储失败。未就绪、未授权或实例关闭时，页面事件不会等待补发。在 beforeSend 内调用此接口会返回 interceptor_active。

框架适配通过 subscribeCollection(listener) 在就绪、授权、撤回、本地重载与 Policy 控制操作后读取当前状态，并只尝试当前页面。通知不包含事件或身份；返回的函数用于取消订阅。原有 page() 保持异步调度语义，其返回值不证明入队。

4. 上下文与属性管理

属性合并顺序为：全局属性 → 会话属性 → 动态属性 → 当前事件属性。后面的同名属性覆盖前面的值。

全局属性

为后续事件提供通用属性：

await sdk.setGlobalProperties({
  app_version: '2.4.0',
  platform_env: 'production',
});

事件属性与 beforeSend 返回的属性受 SDK 处理预算约束。超限事件会被拒收，可在健康快照中查看 event_input_budget。设置全局属性或会话属性时，若更新后的总量超限，调用会拒绝并保留已有值。

会话属性

仅在当前会话有效。会话轮转或 reset() 后清空：

await sdk.setSessionProperties({
  campaign_id: 'spring_sale_2026',
  referral_channel: 'social',
});

// 按需移除指定会话属性
await sdk.removeSessionProperties(['referral_channel']);

动态属性

注册同步函数，在创建事件时取得最新属性（如当前页面或购物车件数）：

sdk.registerDynamicSuperProperties(() => ({
  active_tab: getActiveTabName(),
  cart_total_count: getCartTotalCount(),
}));

// 清除动态超级属性求值函数
sdk.clearDynamicSuperProperties();

该函数须快速、同步返回；不要在其中发起网络请求或返回敏感数据。

5. 用户与业务实体属性

用户属性和业务实体属性通过操作事件上报。并发更新和存储语义由部署接收端实现；SDK 接受操作不代表接收端已经更新数据。

setUserPropertyOnce 由服务端判断目标属性是否已存在；profileAppend 不保证数组去重或并发原子性。
unsetUserProperties 可指定未出现在本地缓存中的属性名。clearUserProperties 按本地已知键产生 $profile_unset，针对本地已知属性，不表示删除所有服务端数据。
未授权、退出采集或关闭实例后，不执行这些操作，也不在恢复授权后补发。

// 设置用户属性（覆盖更新）
await sdk.setUserProperties({ member_level: 'gold', vip: true });

// 仅在首次设置时写入（适合注册渠道、激活时间）
await sdk.setUserPropertyOnce({ first_login_time: '2026-09-21T10:00:00Z' });

// 提交数值增减操作；接收端负责定义并实现更新语义
await sdk.profileIncrement({ login_count: 1, reward_points: 50 });

// 提交列表追加操作（如用户偏好标签，最多 100 项）
await sdk.profileAppend({ interest_tags: ['technology', 'photography'] });

// 移除指定属性
await sdk.unsetUserProperties(['temp_notice']);

// 读取当前已缓存的本地用户属性快照
const profile = sdk.getUserProperties();

业务实体属性

用于上报业务商品、内容、文章等独立维度的实体属性：

// 绑定/更新指定实体属性
await sdk.itemSet('product', 'SKU-88902', {
  name: '无线降噪耳机',
  category: 'audio',
  price: 799.0,
});

// 删除指定实体
await sdk.itemDelete('product', 'SKU-88902');

6. 存储与发送

// 3. 手动触发批量上传（通常仅在单元测试、关键业务跳出或注销前调用）
await sdk.flush();

// 4. 清理本地数据（如用户注销清除本地残留队列）
await sdk.deleteQueuedEvents();
await sdk.clearLocalData();

实际队列存储方式见 getHealthSnapshot().webStorage.outbox。浏览器存储可能被限制或清理；内存模式无法在页面刷新后恢复。队列读写失败时，检查诊断信息。只有确定可以丢弃待发事件时，才调用 deleteQueuedEvents()；请等待调用成功完成。

7. 健康诊断与脱敏导出

运行时健康快照

// 获取内存队列、最近上报状态与错误快照
const health = sdk.getHealthSnapshot();
console.log(`队列积压: ${health.queueSize}, 成功批次: ${health.uploadSuccesses}`);

// 获取最近事件与 Flush 时间线（用于开发者排障）
const timeline = sdk.getDiagnosticsTimeline(20);

存储状态

getHealthSnapshot().webStorage 可查看队列后端和最近的存储故障，无需开启 debug：

const { webStorage } = sdk.getHealthSnapshot();
const { failureCount, reasonCounts, recentFailures, outbox } = webStorage;

outbox.backend 为 indexed_db 或 local_storage 时，队列可在浏览器存储允许的范围内恢复；memory 只在当前页面进程内保留。failureCount 是故障次数，不等于丢失事件数。字段解释与排查步骤见错误码与诊断。

导出诊断报告

SDK 提供诊断报告导出与摘要复制能力。报告不包含完整事件正文；事件 ID、事件名和部分错误/定位字段仍可能带有接入方自定义内容，分享前应检查：

import { copyDiagnosticsSummary, downloadDiagnostics } from '@track-business/sdk-web';

// 复制诊断摘要至剪贴板
await copyDiagnosticsSummary(sdk);

// 下载 JSON 诊断报告；分享前检查接入方自定义字段
downloadDiagnostics(sdk, { filename: 'track-business-diagnostics.json' });

开发环境调试面板 (`devtools`)

需要在开发环境查看队列状态时，可开启调试面板：

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  devtools: {
    defaultOpen: false,
    includeProperties: false, // 生产环境不要开启属性展示
  },
});

8. 元素曝光与预置上下文探测

元素曝光 (`recordExposure`)

记录 $sdk_exposure 事件：

sdk.recordExposure(
  'home_hero_banner', // 曝光位标识
  1200, // 确认时长，毫秒
  0.85, // 可见面积比例，范围 0–1
);

参数分别映射为 $exposure_id、$event_duration 和 $visible_ratio；后两项可省略。附加业务属性时，自定义属性名不要以 $ 开头。

预置上下文探测 (`detectWebPresetContext`)

SDK 初始化时会自动收集并混入标准上下文，无需开发者手动探测：

web.browserFamily: 浏览器家族枚举（chrome, safari, firefox, edge, unknown），不采集原始高危 User-Agent；
device.screenWidth / device.screenHeight: 屏幕逻辑尺寸（CSS 像素）；
device.screenScale: devicePixelRatio 物理像素与逻辑像素缩放比；
device.type: 基于屏幕尺寸与触控能力的设备类型（phone, tablet, desktop, unknown）；
device.locale: 浏览器首选语言（如 zh-CN, en-US）；
device.timezone: IANA 时区（如 Asia/Shanghai）；
network.online: 当前浏览器网络在线状态（布尔值）；
web.viewportWidth / web.viewportHeight: 浏览器视口尺寸。

若需直接获取当前环境预置快照，可调用：

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

const presetContext = detectWebPresetContext();

SDK 会在每个获准事件创建时重新探测环境，页面、屏幕方向和网络状态不会固定在初始化时。 device.orientation 使用 portrait、landscape 或 unknown；device.locale 使用 BCP 47 语言标签，如 zh-CN。无法观测的字段省略，不用模拟值填充。

presetContext 也可提供静态对象或同步函数，用于补充宿主环境。函数仅在事件获准采集后执行，返回内容会复制为该事件的快照；函数异常会记录脱敏诊断，不阻断手工事件。函数应快速返回，不要在其中访问网络或执行耗时存储操作。它不授予位置权限，也不替代位置快照接口。

9. 发送前拦截器 (`beforeSend`)

事件先通过初始授权检查，再调用 beforeSend；回调完成后重新检查授权、隐私规则和 Tracking Plan。支持同步函数或返回 Promise 的异步函数：

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  beforeSend(event) {
    // 丢弃内部调试事件
    if (event.eventName === 'debug_ping') {
      return { action: 'drop', reason: 'filtered_debug_event' };
    }

    // 动态补充或修改业务属性
    return {
      action: 'accept',
      event: {
        ...event,
        properties: {
          ...event.properties,
          injected_runtime: 'browser_spa',
        },
      },
    };
  },
});

IMPORTANT

SDK 强制保护核心元数据：eventId、身份快照、Consent 状态、时间戳及事件名称受框架保护，拦截器不得篡改；
若拦截器执行抛出未捕获异常，SDK 保留原事件继续执行隐私与准入检查，并记录诊断。

异步回调等待上限为 1 秒。超时的事件会被拒绝，诊断原因为 before_send_timeout。在旧 Promise 结束前，后续需要通过该回调的事件会以 before_send_unavailable 拒绝，SDK 不重复调用，也不应用迟到的结果。旧 Promise 结束后，新事件恢复正常处理。同步回调应快速返回，浏览器无法中断正在执行的 JavaScript。

回调中可以等待 grantConsent、denyConsent、setOptOut、grantLocationConsent、 revokeLocationConsent 和 destroy。这些控制操作在回调等待期间执行，返回的 Promise 包含对应的存储及清理工作；当前事件随后按最新状态重新检查。拒绝采集、Opt-out 或关闭实例会使这条尚未入队的事件失效，即使回调内重新授权也不会恢复旧事件。位置撤销会清理已有位置事件，并从当前事件省略位置快照。

上述控制操作在回调期间使用独立的有序通道，可先于普通事件队列中的命令完成；它们不是所有 SDK API 的通用重入机制。身份变更、属性设置和 flush 等串行操作应在回调外完成，不要在 beforeSend 中等待它们。回调内的 track 仍安排在当前事件之后，嵌套事件跳过此回调。

10. 前端框架与混合开发

React 与 Vue 框架官方适配

React (@track-business/sdk-react)：提供 TrackBusinessProvider、useTrackBusiness、useIdentity、useTrackEvent、TrackBusinessErrorBoundary 及 React Router 扩展；
Vue (@track-business/sdk-vue)：提供 createTrackBusinessPlugin、useTrackBusiness、useIdentity、v-track-click 与 v-track-exposure 声明式指令；
身份订阅：客户端提供 getIdentitySnapshot() 与 subscribeIdentity(listener)，返回不可变快照，支持 React 18+ 的 useSyncExternalStore。

详见 React / Vue 框架接入指南。

混合开发 (Hybrid Bridge)

在 Hybrid 容器（如 Android WebView / iOS WKWebView）中，必须由宿主将 Native Bridge 显式注入 SDK，SDK 不自动探测全局桥接对象：

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

注入后，Web 端事件经规范化后转交 Native SDK 入队和上传；Android 调用返回时持久化仍可能在进行中，该转发不修改原生容器的主身份。详见 Hybrid JSBridge 集成指南。

11. 外部设备标识读取

Web SDK 默认不读取外部硬件标识或浏览器指纹。

若企业宿主在合规授权前提下拥有自建标识读取通道，可通过 deviceIdentifierReader 注入：

const sdk = TrackBusinessSDK.create({
  endpoint: 'https://collector.example.com/v1/events/batch',
  projectKey: 'web-public-project-key',
  deviceIdentifierReader: {
    name: 'custom-corporate-reader',
    async read({ consent, purpose }) {
      if (consent !== 'STANDARD' && consent !== 'ADVANCED') return null;
      return await readHostCustomId(purpose);
    },
  },
});

// 主动触发单次受控读取（不会写入事件、身份或本地磁盘）
const reading = await sdk.readDeviceIdentifier('measurement');

若需结合控制面进行服务端设备解析，可使用导出的 FetchDeviceResolutionGateway：

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

const gateway = new FetchDeviceResolutionGateway({ endpoint, projectKey });
const result = await sdk.resolveDeviceIdentifier(gateway, reading);

页面路由模式

pageRouting?: 'history' | 'hash'，默认 history。React HashRouter 或 Vue createWebHashHistory 使用 hash，逻辑路径为 #/ 后的站内路径。该选项不自动开启页面采集；框架接管时仍设置 autoPage: 'manual'。query 和逻辑路径后的锚点变化不轮转 pageViewId；不同路径共用页面插件与框架的导航身份。普通锚点页面保持默认模式。

输出路径继续受 pagePrivacy 约束；框架 page 使用路由模板，其他页面事件及 preset context 应配置 sanitizePath，避免动态实体 ID 出现在事件中。Hash 路由不创建新 Session，也不替代 Consent 门禁。

实例所有权与存储模式

同一页面中，相同 endpoint、projectKey 和 storageNamespace 只创建一个 Runtime。重复 create 的配置等价时返回同一实例；回调和适配器需要使用相同引用。配置冲突抛出固定错误 SDK_SCOPE_ALREADY_OWNED。这些引用是同一实例的别名，任一调用方 destroy() 都会关闭该实例；宿主应统一管理其生命周期。不同项目或命名空间分别创建，跨 Tab 同步仍独立保留。

policy.consentPolicy.storageAllowed 在实例创建时确定。刷新远程 Policy 不切换当前实例的存储模式；需要改变模式时，先关闭实例，再以新配置创建。Consent 撤回仍会清理 SDK 所属残留数据；内存模式不承诺刷新或关闭页面后的事件恢复。

signOut、clearUser、reset、switchUser 的持久化或 Profile 擦除失败，不会恢复旧用户。失败通过固定错误报告，采集与上传暂停，宿主 Consent 决定保持不变。getHealthSnapshot().collectionEnabled 表示当前有效采集状态。处理存储故障后显式重新授权会重试清理；失败时保持暂停，已入队事件保留创建时的身份快照。

SDK 计时器 startTimer/endTimer 的输出字段为 properties.$timer_duration_ms（非负毫秒数），宿主 durationMs 属性不被覆盖。计时事件的严格 Tracking Plan 需声明该测量字段。

有界投递验证

先 await sdk.ready()，再通过 await sdk.verifyDelivery({ timeoutMs: 3000, signal }) 显式验证固定待发送范围。signal 可选，只取消观察，不取消已有上传或释放其租约。返回 DeliveryVerificationResult；acknowledged 只表示有效整批 ACK，empty/unconfirmed 不能表示发送成功。未知计数保留 null，超限会标记 truncated。详见可靠投递。

Web 基础 API ​

常用接口 ​

多域名与 AMP 接入 API ​

1. SDK 初始化与配置 ​

基础工厂初始化 (TrackBusinessSDK.create) ​

初始化参数 ​

页面等自动采集 (createWebBetaClient) ​

可选集成配置 ​

2. 身份识别与生命周期 ​

3. 事件采集 ​

4. 上下文与属性管理 ​

全局属性 ​

会话属性 ​

动态属性 ​

5. 用户与业务实体属性 ​

业务实体属性 ​

6. 存储与发送 ​

7. 健康诊断与脱敏导出 ​

运行时健康快照 ​

存储状态 ​

导出诊断报告 ​

开发环境调试面板 (devtools) ​

8. 元素曝光与预置上下文探测 ​

元素曝光 (recordExposure) ​

预置上下文探测 (detectWebPresetContext) ​

9. 发送前拦截器 (beforeSend) ​

10. 前端框架与混合开发 ​

React 与 Vue 框架官方适配 ​

混合开发 (Hybrid Bridge) ​

11. 外部设备标识读取 ​

页面路由模式 ​

实例所有权与存储模式 ​

有界投递验证 ​