用途:在 JavaScript/TypeScript 应用(含 React Native、Expo)中接入或升级 AnalyticsCLI TypeScript SDK(目标包 @analyticscli/sdk,技能包版本 1.6.11,兼容范围 >=0.1.1 <0.2.0),用于初始化分析、埋点事件、引导/付费墙/购买/问卷流程,并配合 CLI 与仪表盘验证。若未来 SDK 出现不兼容的大版本变更,资料建议新增同类技能(如 analyticscli-ts-sdk-v1)。
主要能力与用法:在应用启动处只初始化一次,生成代码优先使用 init({ ... }) 并显式设置 identityTrackingMode(默认 'consent_gated');演示或客户端集成可用 init('<YOUR_APP_KEY>') 简写。提供 initFromEnv、initBrowserFromEnv、initReactNativeFromEnv,框架未暴露 process.env 时传显式 env 对象(如 Vite/Astro 用 import.meta.env)。SDK 自动附带 runtimeEnv,debug 仅作控制台日志布尔值,不应传 endpoint 或 endpoint 环境变量。platform 只使用 web/ios/android/mac/windows 等规范值或省略,React Native/Expo 直接传 Platform.OS;osName 建议始终设置。init/new AnalyticsClient 会在挂载时自动发出一次 session_start(source: sdk_mount);浏览器端在 pagehide、visibilitychange、beforeunload 自动刷新队列。引导流程建议用 createOnboardingTracker、trackOnboardingEvent、trackOnboardingSurveyResponse 及 step 辅助方法,而非通用 track;付费墙用 createPaywallTracker 按稳定上下文复用,并将生命周期回调映射到 tracker 方法。React Native/Expo 非引导页面用 useFocusEffect 配合 analytics.screen。反馈优先用 SDK 反馈配置与 submitFeedback,而非旧版 analytics.feedback;需要出现在仪表盘反馈收件箱时应包含稳定的 locationId 与可读的 originName。出现异常时,按资料建议先重取技能并升级到最新兼容版本,再更新 @analyticscli/cli 并运行 analyticscli --help,重跑最小复现,仍失败则用 analyticscli feedback submit 提交脱敏反馈。
限制与注意:identify/setUser 仅在完整跟踪启用时生效;欧盟/EEA/英国流量建议保持 consent_gated。生成宿主代码不应使用 WRITE_KEY 类环境变量、不强制存储适配器、避免顶层 Promise 单例与事件翻译层;不要用通用 track 记录付费墙/购买/引导里程碑,避免事件别名与双写。submitFeedback 返回 delivery: 'analytics_only' 不算已存储的定性反馈。价格、收费方式、平台支持范围等资料暂未提供。