feat(analytics): add consent-gated activation-funnel analytics via PostHog
Installs are up 615% but 7-day retention is ~0% and we had no analytics SDK to see where users drop off. Adds a thin PostHog wrapper (src/lib/analytics.ts) that tracks app_opened, connection_form_submitted, connection_attempted, connection_succeeded/failed (with a coarse error_class, e.g. the known 401 auth bug), message_sent, and response_received. PostHog was chosen over Aptabase for its GMS-free JS-only RN SDK (fine for the F-Droid/no-Firebase build), EU-hosted/self-host option, and generous free tier. Analytics shares the exact same consent flag as Sentry (telemetry.ts now gates both) so zero network calls happen without explicit opt-in. Requires a new EXPO_PUBLIC_POSTHOG_KEY CI secret (wired into build.yml, publish-fdroid.yml, publish-play-store.yml, and documented in publish-app-store.yml alongside the existing Sentry secrets). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NJKAQ6HAikWGQK7PGZ5Y4E
This commit is contained in:
engineer
139
src/lib/analytics.ts
Normal file
139
src/lib/analytics.ts
Normal file
@@ -0,0 +1,139 @@
|
||||
// Centralised PostHog wrapper for activation-funnel analytics.
|
||||
//
|
||||
// Mirrors sentry.ts's shape and guarantees:
|
||||
// 1. Strict no-op when no API key is configured (dev/CI builds need no secrets).
|
||||
// 2. Strict no-op when the user has not granted telemetry consent — this
|
||||
// module never calls PostHog.init/capture on its own; it is only ever
|
||||
// driven by ./telemetry.ts, which gates BOTH Sentry and analytics behind
|
||||
// the exact same "opencode_telemetry_consent" flag.
|
||||
// 3. No PII in event properties: never pass server URLs, tokens, prompts,
|
||||
// or file contents. Only coarse, enumerated event names + small typed
|
||||
// properties (booleans, enums, counts).
|
||||
//
|
||||
// Chosen SDK: PostHog (posthog-react-native), self-instantiated (no
|
||||
// PostHogProvider / autocapture) so the app controls exactly what is sent —
|
||||
// same "explicit event, no magic" posture as sentry.ts.
|
||||
|
||||
import PostHog from "posthog-react-native"
|
||||
import * as SecureStore from "expo-secure-store"
|
||||
import { log } from "./logbuffer"
|
||||
|
||||
const API_KEY = process.env.EXPO_PUBLIC_POSTHOG_KEY
|
||||
// EU by default (GDPR-friendly region for opencode's mostly-EU/self-hosted user base).
|
||||
// Override with EXPO_PUBLIC_POSTHOG_HOST for a self-hosted instance.
|
||||
const HOST = process.env.EXPO_PUBLIC_POSTHOG_HOST || "https://eu.i.posthog.com"
|
||||
|
||||
const FIRST_OPEN_KEY = "opencode_analytics_first_open_done"
|
||||
|
||||
let client: PostHog | null = null
|
||||
let enabled = false
|
||||
|
||||
/** Coarse, non-identifying failure buckets — never include the raw error string
|
||||
* (it may embed hostnames/tokens/paths). Reuses the vocabulary already
|
||||
* established by diagnostics-classify.ts's Classification type. */
|
||||
export type ConnectionErrorClass =
|
||||
| "malformed-url"
|
||||
| "no-internet"
|
||||
| "server-unreachable"
|
||||
| "unauthorized"
|
||||
| "tls-error"
|
||||
| "timeout"
|
||||
| "unknown"
|
||||
|
||||
/** Activation-funnel events. Keep this list in 1:1 sync with the funnel steps
|
||||
* tracked in the product analytics dashboard. */
|
||||
export enum AnalyticsEvent {
|
||||
/** App process started and the user has an existing telemetry decision of "granted". */
|
||||
AppOpened = "app_opened",
|
||||
/** User tapped Connect/Save with a non-empty server URL (quick or advanced mode). */
|
||||
ConnectionFormSubmitted = "connection_form_submitted",
|
||||
/** A real network call to test/establish the connection started. */
|
||||
ConnectionAttempted = "connection_attempted",
|
||||
/** The connection attempt succeeded (health check / project fetch responded). */
|
||||
ConnectionSucceeded = "connection_succeeded",
|
||||
/** The connection attempt failed. Always paired with `error_class`. */
|
||||
ConnectionFailed = "connection_failed",
|
||||
/** User sent a prompt/message to an agent session (excludes slash commands). */
|
||||
MessageSent = "message_sent",
|
||||
/** An agent response finished streaming (session transitioned busy -> idle). */
|
||||
ResponseReceived = "response_received",
|
||||
}
|
||||
|
||||
export function initAnalytics() {
|
||||
if (enabled) return
|
||||
if (!API_KEY) {
|
||||
log.info("analytics", "no API key configured — analytics disabled")
|
||||
return
|
||||
}
|
||||
try {
|
||||
client = new PostHog(API_KEY, {
|
||||
host: HOST,
|
||||
// We call track() explicitly at each funnel step — no implicit capture.
|
||||
captureAppLifecycleEvents: false,
|
||||
})
|
||||
enabled = true
|
||||
log.info("analytics", "initialized", `host=${HOST}`)
|
||||
} catch (e) {
|
||||
log.warn("analytics", "init failed", String(e))
|
||||
}
|
||||
}
|
||||
|
||||
export async function shutdownAnalytics() {
|
||||
if (!enabled || !client) return
|
||||
enabled = false
|
||||
const c = client
|
||||
client = null
|
||||
try {
|
||||
await c.shutdown()
|
||||
} catch (e) {
|
||||
log.warn("analytics", "shutdown failed", String(e))
|
||||
}
|
||||
log.info("analytics", "disabled by user")
|
||||
}
|
||||
|
||||
export function analyticsEnabled(): boolean {
|
||||
return enabled
|
||||
}
|
||||
|
||||
/** Flat, JSON-safe event properties — keep it to primitives so nothing
|
||||
* accidentally nests an object that could carry a URL/token. */
|
||||
export type AnalyticsProps = Record<string, string | number | boolean | null>
|
||||
|
||||
/** No-op unless consent has been granted (initAnalytics() was called) and a
|
||||
* key is configured. Never throws. */
|
||||
export function track(event: AnalyticsEvent, props?: AnalyticsProps) {
|
||||
if (!enabled || !client) return
|
||||
try {
|
||||
client.capture(event, props)
|
||||
} catch (e) {
|
||||
log.warn("analytics", "capture failed", String(e))
|
||||
}
|
||||
}
|
||||
|
||||
/** Fire AppOpened with `is_first_open`. The "seen before" flag is only ever
|
||||
* read/written once consent is granted (this function is itself a no-op
|
||||
* without consent), so nothing is recorded locally pre-consent either. */
|
||||
export async function trackAppOpened() {
|
||||
if (!enabled) return
|
||||
let isFirstOpen = false
|
||||
try {
|
||||
const seen = await SecureStore.getItemAsync(FIRST_OPEN_KEY)
|
||||
isFirstOpen = !seen
|
||||
if (isFirstOpen) await SecureStore.setItemAsync(FIRST_OPEN_KEY, "1")
|
||||
} catch {
|
||||
// SecureStore unavailable — still fire the event, just without the flag.
|
||||
}
|
||||
track(AnalyticsEvent.AppOpened, { is_first_open: isFirstOpen })
|
||||
}
|
||||
|
||||
/** Classify a connection failure into a coarse bucket without leaking the
|
||||
* raw error message (which can contain hostnames/IPs). */
|
||||
export function classifyConnectionError(message: string | undefined): ConnectionErrorClass {
|
||||
const m = (message || "").toLowerCase()
|
||||
if (/401|unauthoriz/.test(m)) return "unauthorized"
|
||||
if (/ssl|tls|certificate|handshake/.test(m)) return "tls-error"
|
||||
if (/timeout|timed out/.test(m)) return "timeout"
|
||||
if (/network request failed|unreachable|econnrefused|fetch failed/.test(m)) return "server-unreachable"
|
||||
if (/malformed|invalid url/.test(m)) return "malformed-url"
|
||||
return "unknown"
|
||||
}
|
||||
@@ -1,19 +1,21 @@
|
||||
/**
|
||||
* Telemetry consent + initialisation gate.
|
||||
*
|
||||
* Wraps sentry.ts so that initSentry() is only called when the user has
|
||||
* explicitly opted in. Consent state is persisted in expo-secure-store so
|
||||
* it survives app restarts.
|
||||
* Wraps sentry.ts AND analytics.ts so that initSentry()/initAnalytics() are
|
||||
* only called when the user has explicitly opted in. Both crash reporting
|
||||
* and activation-funnel analytics share this single consent flag — there is
|
||||
* no separate toggle for analytics. Consent state is persisted in
|
||||
* expo-secure-store so it survives app restarts.
|
||||
*
|
||||
* Usage:
|
||||
* import { loadTelemetryConsent, setTelemetryConsent, hasTelemetryConsent } from './telemetry'
|
||||
*
|
||||
* // On app start — call BEFORE trying to initialise Sentry.
|
||||
* // On app start — call BEFORE trying to initialise Sentry/analytics.
|
||||
* const state = await loadTelemetryConsent() // 'granted' | 'denied' | 'unknown'
|
||||
* if (state === 'granted') initSentry()
|
||||
* if (state === 'granted') { initSentry(); initAnalytics() }
|
||||
*
|
||||
* // After the user taps "Allow" in the consent modal:
|
||||
* await setTelemetryConsent(true) // persists + calls initSentry() if not already done
|
||||
* await setTelemetryConsent(true) // persists + calls initSentry()/initAnalytics() if not already done
|
||||
*
|
||||
* // Check in Settings screen:
|
||||
* const current = hasTelemetryConsent() // boolean | null (null = not yet decided)
|
||||
@@ -21,6 +23,7 @@
|
||||
|
||||
import * as SecureStore from "expo-secure-store"
|
||||
import { disableSentry, initSentry, sentryEnabled } from "./sentry"
|
||||
import { initAnalytics, shutdownAnalytics, analyticsEnabled } from "./analytics"
|
||||
|
||||
const CONSENT_KEY = "opencode_telemetry_consent"
|
||||
|
||||
@@ -78,11 +81,13 @@ async function applyTelemetryConsent(granted: boolean): Promise<void> {
|
||||
await SecureStore.setItemAsync(CONSENT_KEY, "granted")
|
||||
_resolved = true
|
||||
if (!sentryEnabled()) initSentry()
|
||||
if (!analyticsEnabled()) initAnalytics()
|
||||
return
|
||||
}
|
||||
|
||||
_resolved = false
|
||||
await disableSentry()
|
||||
await shutdownAnalytics()
|
||||
try {
|
||||
await SecureStore.setItemAsync(CONSENT_KEY, "denied")
|
||||
} catch (error) {
|
||||
|
||||
Reference in New Issue
Block a user