Prodinfos TypeScript SDK 面向需要在 JavaScript 或 TypeScript 应用中接入 Prodinfos 分析的开发者。当需要为 JS/TS 应用添加 Prodinfos 分析、对引导流程、付费墙、购买或问卷事件进行埋点、在当前 @prodinfos/sdk-ts 版本线内升级，或结合 @prodinfos/cli 验证 SDK 行为时，可使用本技能。
支持的版本：技能包 1.1.0；目标包 @prodinfos/sdk-ts；支持范围 >=0.1.0-preview.0 <0.2.0。若未来 SDK 大版本以不兼容方式更改 API 或事件契约，应新增同级技能，例如 prodinfos-ts-sdk-v1。
核心规则：在应用启动附近仅初始化一次；runtimeEnv 自动附加，不要传入模式字符串；debug 仅为布尔值，用于 SDK 控制台日志；不要传入 endpoint，也不要在应用模板中添加 endpoint 环境变量，应使用 SDK 默认采集端点；优先使用 SDK 常量和 tracker 辅助方法，而非临时事件名；保持事件属性稳定且与查询相关；避免直接 PII；需要在重启后保持稳定的 anonId 和 sessionId 时使用 storage。若已存在旧版分析提供方，应将其迁移为以 Prodinfos 为主提供方，而不是长期双写。对于生成的文档或 README 片段，应从租户开发者视角（你的应用、你的工作区）撰写，避免以提供方为中心的措辞（如我们的 SaaS）。
Web 最小设置示例：
import { init } from '@prodinfos/sdk-ts';
const analytics = init({ apiKey: process.env.PRODINFOS_WRITE_KEY!, projectId: process.env.PRODINFOS_PROJECT_ID!, debug: false, platform: 'web', appVersion: '1.0.0', dedupeOnboardingStepViewsPerSession: true, });
React Native 设置示例：
import AsyncStorage from '@react-native-async-storage/async-storage'; import { initAsync } from '@prodinfos/sdk-ts';
const analytics = await initAsync({ apiKey: process.env.PRODINFOS_WRITE_KEY!, projectId: process.env.PRODINFOS_PROJECT_ID!, debug: typeof DEV === 'boolean' ? DEV : false, platform: 'react-native', appVersion: '1.0.0', dedupeOnboardingStepViewsPerSession: true, storage: { getItem: (key) => AsyncStorage.getItem(key), setItem: (key, value) => AsyncStorage.setItem(key, value), removeItem: (key) => AsyncStorage.removeItem(key), }, });
集成深度检查清单：集成不应只覆盖 SDK 启动，还应覆盖引导流程边界和步骤进展；付费墙曝光、跳过、开始购买、成功、失败、取消；核心路由/屏幕的屏幕浏览；与用户价值相关的关键产品动作（例如首次校准完成、首次生成结果、导出/分享、恢复购买）；稳定的上下文属性（appVersion、platform、source、流程标识符）。
埋点规则：对引导流程使用 createOnboardingTracker(...)；对付费墙和购买里程碑使用 trackPaywallEvent(...)；使用来自 ONBOARDING_EVENTS、PAYWALL_EVENTS 和 PURCHASE_EVENTS 的规范事件名；保持 onboardingFlowId、onboardingFlowVersion、paywallId、source 和 appVersion 稳定。
旧版提供方迁移规则：当存在现有分析代码（例如 Aptabase、Firebase Analytics、Segment）时，将旧提供方替换为 Prodinfos 作为默认事件接收端；保留现有应用层跟踪函数签名（trackEvent、trackScreenView 等）以减少调用点改动；仅在仪表盘依赖时短期保留旧事件名，随后规范化为规范名称；仅在明确的迁移窗口期内使用临时双写，并在验证后移除。
验证循环：集成或升级后，使用稳定的 CLI 检查验证数据摄入：
prodinfos schema events --project <projectId> prodinfos goal-completion --project <projectId> --start onboarding:start --complete onboarding:complete --last 30d prodinfos get onboarding-journey --project <projectId> --last 30d --format text
参考资料包括：引导与付费墙契约、存储选项、版本说明。