核心用法
Outlit SDK Integration 是 Outlit 官方提供的多平台 SDK 集成决策树指南，旨在帮助开发者快速将产品和网站追踪接入 Outlit 客户上下文图谱。覆盖 @outlit/browser、@outlit/node 及 Rust outlit crate 三大核心 SDK。
典型工作流：
1. 检测先行：扫描现有依赖确认 Outlit 是否已安装
2. 快速连接：识别框架（React/Next/Vue/Svelte/Angular/Astro/Node/Rust 等），选择对应 SDK 并配置公钥环境变量
3. 最小化启动：仅初始化基础追踪，验证连接成功后进入完整集成
4. 完整集成：按需叠加身份管理、激活事件、计费追踪、服务端追踪、合规 consent 等模块
关键决策点：
- Consent：支持 CMP 集成或手动控制
autoTrack开关 - Identity：浏览器端用
setUser()/OutlitProvider user属性；服务端用identify()配合email/userId/customerId/fingerprint - Activation：手动调用
user.activate()标记产品价值时刻，避免使用已废弃的engaged/inactiveAPI - Billing：账户级计费事件，TypeScript 优先用
customerId，Rust 仍支持 domain 链式调用 - Server/Native：Node 后端、Rust CLI/Tauri、React Native 等场景使用
@outlit/node或 Rust crate，必须flush()或shutdown()
显著优点
- 官方权威性：直接来自 Outlit 团队，API Guardrails 明确标注当前正确用法与废弃模式
- 多平台覆盖：浏览器（自动捕获页浏览、表单、日历嵌入）、Node 服务端、Rust 原生/桌面/CLI 统一支持
- 身份解析能力强：
customerId区分账户/工作空间层级，fingerprint支持设备级匿名追踪 - 开箱即用：默认自动捕获 SPA 导航、会话时长、Cal.com/Calendly 预约等常见场景
- 隐私合规友好：内置
autoTrack: false模式，支持 GDPR/CCPA 前置 consent 决策
潜在局限与风险
- API 版本敏感：文档强调旧字段如
customerDomain、privateKey、visitorId已废弃，历史集成需主动迁移 - 服务端身份不关联浏览器 Cookie：服务端
identify()无法自动链接浏览器访客历史，必须双端分别调用 - 日历嵌入限制：Cal.com/Calendly 客户端嵌入无法获取参会者邮箱，需配合服务端 webhook 补充身份
- 队列边界问题：浏览器
user.activate()仅缓冲 10 条事件，身份设置延迟可能导致丢激活 - Rust API 差异：Rust billing 方法仍使用 domain 起始链式调用，与 TypeScript
customerId优先模式不一致 - 无运行时凭证自检：Skill 本身不验证 Outlit key，错误配置需通过 Network/控制台排查
适合人群
- 需要将产品分析从 PostHog/Amplitude/Mixpanel/Segment 迁移或并存的团队
- 构建多租户 SaaS、需区分用户身份与账户/工作空间层级的开发者
- 使用 Next.js、Nuxt、SvelteKit、Tauri、Electron 等现代全栈/跨端框架的技术团队
- 需要 EU 合规 consent 管理的企业场景
常规风险
| 风险场景 | 说明 |
|---------|------|
| 密钥泄露 | 公钥 `pk_` 可安全暴露于客户端；私钥 `OUTLIT_PRIVATE_KEY` 不应存在，误用会导致安全问题 |
| 服务端事件丢失 | Serverless 环境未 `await flush()` 导致事件未送达 |
| 身份断层 | 仅服务端 identify 未浏览器 setUser，导致访客历史断裂 |
| 废弃 API 残留 | 使用 `user.engaged()`/`user.inactive()` 或 `customerDomain` 造成兼容隐患 |
| 敏感数据上传 | 表单自动捕获会脱敏，但自定义 `track()` 属性需主动避免 PII/密钥泄露 |
来源与可信度
Outlit 官方仓库提供的 Skills CLI 技能，文档链接指向 docs.outlit.ai 官方域名，API Guardrails 和版本废弃说明表明维护活跃。