从其他埋点 SDK 迁移

本文帮助使用其他埋点 SDK 的团队规划迁移。接入前请核对身份、事件、Consent 和上传语义，再确定事件名及属性的映射关系。

1. 推荐迁移顺序

text

冻结旧 SDK 写入范围
  → 建立事件与身份映射表
  → 在测试环境验证事件、身份、Consent 与投递
  → 双写或灰度验证事件数量与身份链路
  → 切换读取方
  → 关闭旧 SDK，保留 Outbox 与回滚窗口

条件允许时分阶段调整身份模型、事件命名、服务端协议和 Consent 配置，便于定位差异。

2. 核心 API 语义映射

常见旧 SDK 语义	Track Business SDK	迁移注意事项
`track(name, properties)`	`track(name, properties)`	事件创建时固化身份、Session、Consent 和全局属性快照
`page()` / 页面浏览	Web `page()` 或 `autoPage`	自动页面插件默认关闭；URL 会去除 query、fragment 和认证信息
`screen(name)`	Android/iOS `recordScreenView(name)`	页面名由宿主显式提供，不从 View、Compose 树或页面文本推导
`identify(userId, traits)`	`identify(userId)` + `setUserProperties(...)`	业务身份与用户画像操作分开，避免把画像字段误作身份标识
`login(userId)`	`identify(userId)`	客户端业务身份绑定统一使用 `identify`，线上事件统一为 `$identity_login`
`switchUser(userId, traits)`	`switchUser(userId)` + `setUserProperties(...)`	先完成换人，再写入新用户画像；身份接口不接收画像属性
`reset()` / `logout()`	`reset()`、`clearUser()`、`signOut()` 或 `switchUser()`	默认退出用 `signOut`；保留匿名旅程才用 `clearUser`；换人必须 `switchUser`
`group(accountId)`	`group(groupId, traits?)`	`groupId` 与 `tenantId` 是不同字段，不会隐式互相赋值
`alias()`	`alias()`	仅表达身份绑定动作，不允许客户端自行合并 `resolvedPersonId`
`flush()`	`flush()`	表示触发/等待上传流程；最终 ACK 仍由 Outbox 和 Transport 决定
`optOut()` / `setOptOut()`	`setOptOut(true)`	阻止新事件、停止自动插件并清理本地待上传队列

3. Segment / RudderStack 类 SDK

这类 SDK 通常已经具备 track、page、identify、group、alias 和 reset。迁移重点是保留这些业务语义，同时把 Destination 配置从客户端 SDK 中移出。

const sdk = TrackBusinessSDK.create({ endpoint, projectKey });

// 需要等待初始化完成时使用 ready()
await sdk.ready();

await sdk.identify(account.userId);
await sdk.setUserProperties({ plan: account.plan });
await sdk.group(account.organizationId);
sdk.track('checkout_completed', { orderId: order.id, amount: order.amount });
await sdk.flush();

按需把原来的 middleware / destination 逻辑迁移为：

若团队使用本地 Tracking Plan，将事件字段约束放入计划并在 warn 模式观察；基础接入不依赖远程 Tracking Plan 服务；
受控字段补充放入 Enrichment Plugin；
上报协议和 ACK 处理交给 SDK Transport；
业务身份切换仍由宿主显式调用 switchUser 或 reset。

不要把服务端 Destination 路由、服务端 Secret 或 resolvedPersonId 放进客户端适配器。

4. PostHog / GA4 类 SDK

这类 SDK 往往同时提供自动页面、自动点击、归因和调试能力。迁移时应逐项核对各平台的采集配置。自动采集插件需按平台指南启用；原生默认的前后台 flush 调度不等同于生命周期事件采集。

迁移时建议先只启用：

手动 track / page / screen；
web-attribution（仅白名单 Campaign 参数）；
明确 allowlist 的 DOM click 或原生交互；
按业务需要选择异常、性能或生命周期插件，并核对数据范围。

暂不要直接迁移：

全量 DOM / 表单自动采集；
Session Replay；
复杂设备指纹；
依赖 SDK 内部用户合并规则的自动身份归并。

插件需满足自身配置与 Consent 要求；若启用了本地 Tracking Plan，还需通过相应事件规则校验。

5. Amplitude / Mixpanel 类 SDK

这类 SDK 的迁移重点通常是离线缓存、用户属性和事件属性。Track Business SDK 的等价边界如下：

旧模型	建议迁移位置
用户属性 `set`	Profile `set` 操作事件；接收端更新语义由部署实现决定
用户属性 `increment`	Profile `increment`
用户属性数组追加	Profile `append`
用户属性删除	Profile `delete`
Item / 产品属性	Profile Item 操作
SDK 本地缓存	平台 Durable Outbox，宿主不直接操作 SQLite/Room/IndexedDB
失败重试	SDK 内置 lease、退避、整批确认和 dead-letter

迁移校验不能只比较请求是否发出，还要比较：

同一 eventId 重试是否保持不变；
成功响应是否整批删除，非法确认体是否整批保留；
断网、429、500 和进程重启后是否恢复；
opt-out 后本地待上传事件是否被清理。

6. 神策 / 国内埋点 SDK 类迁移

迁移到 Track Business SDK 时，建议保留业务事件名和业务属性含义，但重新确认以下字段：

用户标识：业务 userId、匿名 anonymousId、安装 installationId 不要混成一个 distinct_id；
组织标识：groupId、tenantId、groupTraits 分开建模；
设备标识：GAID/OAID/App Set ID 只能作为显式、Consent 门控的外部标识读取结果，不参与主身份自动合并；
页面和控件：使用宿主显式的 page/screen/interaction 语义，不复制 Runtime Swizzling 或 View 树扫描；
自定义属性：先定义字段语义与类型；若团队使用本地 Tracking Plan，可在 warn 模式验证。

7. 双写与灰度验收清单

双写期间，旧 SDK 和 Track Business SDK 必须使用不同的本地队列或明确的事件去重键，不能让两个 SDK 争抢同一份 Outbox。至少验证：

同一业务动作在两边的事件数量和关键属性一致；
identify → track → clearUser/signOut/switchUser → track 的身份边界一致；
刷新、关闭页面、切后台和进程重启后的事件最终状态一致；
Consent 降级和 opt-out 不会继续产生自动事件；
分享 Diagnostics 前检查事件名、插件名和错误摘要等自定义内容，并移除其中可能包含的用户标识、凭据或其他敏感信息。

若迁移流程采用本地 Tracking Plan，先根据 warn 结果修正数据，再由数据治理负责人决定是否启用 block。确认数据消费方切换并保留既定回滚窗口后，再移除旧 SDK。

8. 兼容范围

Track Business SDK 当前不承诺：

兼容其他厂商 SDK 的私有存储格式；
让旧 SDK 的 distinct_id 自动等同于新的 userId；
在客户端复制服务端 Identity Graph；
通过兼容层继续允许隐式账号切换；
使用本地测试 Gateway 替代部署环境的接收服务。

如需迁移历史身份关联，应由业务后端基于原 SDK 的业务用户标识和服务端数据完成一次性映射，客户端只负责从切换版本开始生成符合新契约的事件。

从其他埋点 SDK 迁移 ​

1. 推荐迁移顺序 ​

2. 核心 API 语义映射 ​

3. Segment / RudderStack 类 SDK ​

4. PostHog / GA4 类 SDK ​

5. Amplitude / Mixpanel 类 SDK ​

6. 神策 / 国内埋点 SDK 类迁移 ​

7. 双写与灰度验收清单 ​

8. 兼容范围 ​