可观测性
受隐私同意门控、无密钥时无操作的 PostHog 分析与 Sentry 崩溃上报。
模板内置两套可观测性集成：用于产品分析的 PostHog 与用于崩溃/错误上报的 Sentry。两者都是 Integrated，都在无密钥时无操作，且分析受隐私同意门控——这是通过 App 审核的一项标志性行为。 本页讲每套如何接线，以及让它们审核安全的隐私规则。
关键文件
分析（PostHog）
AnalyticsController 封装 PostHog SDK。关键设计点：start() 不在 App.init 中调用——而是在用户接受后
由隐私同意门控调用，因为 App 审核人员会标记在任何同意 UX 之前就触发的
分析 SDK。
为让调用点保持简单，在 start() 之前 post 的事件会被缓冲（上限 50），并在 start 时排空——这样你可以
从任何地方 track(...) 而无需知道同意是否已通过：
func track(_ event: AnalyticsEvent) {
guard isConfigured else { buffer(.track(event)); return } // 同意前 → 缓冲
guard isEnabled else { return } // 无密钥 / 已禁用 → 丢弃
PostHogSDK.shared.capture(event.name, properties: event.properties)
}类型化事件
事件是一个类型化的 AnalyticsEvent 枚举，而非到处的字符串式调用点——原始 PostHog 名称与属性字典集中一处：
enum AnalyticsEvent {
case screenViewed(path: String, params: [String: String]? = nil)
case onboardingCompleted(slideCount: Int)
case paywallViewed(source: String?)
case referralInviteShared(channel: String?)
case purchaseCompleted(tier: String, period: String, source: String?)
case purchaseRestored(source: String?)
}身份
控制器订阅 auth 会话流：登录时用 Supabase 用户 UUID（+ 邮箱）执行 identify，登出时执行 reset——因此
事件绑定到正确的人，且不会跨账户串味。
配置与总开关
| 密钥 | 效果 |
|---|---|
POSTHOG_API_KEY | 启用分析；缺失 → isEnabled == false，所有调用无操作 |
POSTHOG_HOST | 默认为 https://us.i.posthog.com |
POSTHOG_DISABLED | true → 即使有密钥也硬性关闭 |
POSTHOG_DEBUG | SDK 详细日志 |
屏幕浏览手动上报（captureScreenViews = false），以便你掌控路径；应用生命周期事件开启。
崩溃上报（Sentry）
SentryReporter.shared.start(dsn:authRepository:) 从 AppEnvironment.init 调用一次，SENTRY_DSN 为空时
无操作。它设置环境（DEBUG 下 development，否则 production）、10% 的 traces 采样率，并把 auth 身份映射到
Sentry 用户（登出时清空）。
错误总线 + 边界
错误经由一个小的全局总线抵达 Sentry，而非散落各处的 try/catch：
视图模型 → AppErrorBus.shared.post("message", underlyingError: err)
│
▼
ErrorBoundary（挂在 RootView） → 全屏兜底卡片
│ “发送报告”
▼
SentryReporter.captureUserFeedback(comment) → Sentry 反馈收件箱ErrorBoundary 包住整个应用（见应用门控）。其发送报告按钮把用户评论作为
Sentry 用户反馈附上；堆栈细节仅在 DEBUG 显示，发布构建中绝不显示。你也可以直接调用
SentryReporter.shared.capture(error:) / capture(message:)。
dSYM 上传警告不影响流程。 上传时出现“did not include a dSYM for Sentry.framework”警告，不会阻止 TestFlight 或购买——它只影响部分帧的符号化。见疑难排查。
隐私与 App 审核
- 先同意再跟踪。 分析在同意门控通过前根本无法触发（
start()以接受为门槛）。保持这样。 - App 隐私标签。 填写 App 隐私时声明各 SDK 收集了什么——PostHog（用量/标识符）、Sentry（崩溃诊断）， 外加 RevenueCat + Supabase。映射见发布页。
- ATT 是独立的。 权限界面的跟踪卡管的是第三方 IDFA 跟踪；第一方 PostHog 分析不依赖 ATT 同意。
验证
- 无密钥时，应用照常运行——无分析、无崩溃上报、不崩溃。
- 设好
POSTHOG_API_KEY后接受同意 → 事件出现在 PostHog；同意前的事件也会到达（缓冲后排空）。 - 设好
SENTRY_DSN后触发AppErrorBus.shared.post(...)→ 边界卡片出现，发送报告落到 Sentry 反馈收件箱。 -
POSTHOG_DISABLED = true即使有密钥也抑制分析。