Analytics

Scope

This is a code-derived inventory of what Char sends to PostHog across:

• apps/web (browser events)
• apps/desktop + plugins/analytics (desktop events)
• apps/api + proxy/subscription crates (server-side events)

Collection paths

Web (apps/web)

• PostHog is initialized in apps/web/src/providers/posthog.tsx only when:
  • VITE_POSTHOG_API_KEY is set
  • build is not dev (!import.meta.env.DEV)
• Enabled options:
  • autocapture: true
  • capture_pageview: true

Desktop (apps/desktop + plugins/analytics)

• Frontend calls analyticsCommands.event, analyticsCommands.setProperties, and analyticsCommands.identify.
• Rust plugin forwards to hypr_analytics::AnalyticsClient in plugins/analytics/src/ext.rs.
• Distinct ID for desktop telemetry is hypr_host::fingerprint() (hashed machine UID).

API/server (apps/api + crates)

• API builds a PostHog client in production in apps/api/src/main.rs.
• Request middleware maps x-device-fingerprint and auth user ID into request extensions in apps/api/src/auth.rs.
• LLM/STT/trial analytics emit from backend crates (details below).

Identity and distinct IDs

Automatic desktop event enrichment

Every desktop event(...) call is enriched in plugins/analytics/src/ext.rs with:

This enrichment applies to desktop frontend events and Rust plugin event_fire_and_forget events (for example notification/window events).

Event catalog

Web custom events

Notes:

• PostHog autocapture and pageview are also on (production only), so PostHog default browser events are collected in addition to the custom events above.
• Web auth callback calls identify(userId, { email }) in apps/web/src/routes/_view/callback/auth.tsx.

Desktop product events

Desktop notification events

API/server events

UTM parameters on owned links

All owned outbound links that drive traffic to char.com carry UTM parameters so installs and page visits can be attributed by source in PostHog.

Convention

Where UTMs are applied

Rules

• Append ?utm_source=...&utm_medium=...&utm_campaign=organic to the URL.
• If the URL already has query parameters, use & instead of ?.
• Place UTM parameters before any #fragment (e.g., ?utm_source=app&utm_medium=settings&utm_campaign=organic#section).
• Do not add UTMs to internal same-site navigation (relative links), API endpoints, OG meta tags, CI config URLs, or links to third-party sites.
• Blog-to-blog cross-links (char.com/blog/... → char.com/blog/...) do not get UTMs since they are internal navigation.

How this connects to PostHog

PostHog automatically captures UTM parameters from the landing page URL as properties on the user's first pageview event. This means:

• download_clicked events can be segmented by the UTM properties of the session that led to them.
• Stage 1 (Acquisition) and Stage 2 (Install conversion) attribution improves because you can see which source drove the visit.
• The utm_source / utm_medium breakdown directly answers "where do our installs come from?"

User journey funnel

The user lifecycle is divided into 8 stages. Each stage lists the PostHog events that measure it, how identity linking works at that point, and known gaps.

Stage 1: Acquisition (website visits)

Goal: measure traffic to the website.

Identity: anonymous PostHog browser distinct ID. No user identity yet.

Stage 2: Converting visits to installs

Goal: measure how many website visitors download and open the app.

Identity linking: download_clicked fires with anonymous browser ID. show_main_window fires with machine fingerprint. These two IDs are not linked at this point — there is no mechanism to pass the browser identity into the desktop app at download time. Conversion rate between these two events can only be measured at cohort level (e.g., X downloads this week, Y first app opens this week), not per-user.

Gap: no explicit install-complete event. Install is inferred from first show_main_window.

Stage 3: Onboarding

Goal: measure onboarding progress and completion.

Identity linking: desktop sign-in opens char.com/auth in the user's default browser. The web auth callback calls posthog.identify(supabaseUserId), which merges the anonymous browser ID with the Supabase user ID. The desktop then calls identify(supabaseUserId) with $anon_distinct_id = machine fingerprint. This links browser → Supabase user ID → machine fingerprint. Because the login opens in the same browser where the user may have previously clicked download, PostHog can retroactively merge download_clicked with the authenticated user — but only if the same browser is used for both download and login.

Stage 4: Activation (first summary)

Goal: measure whether a user gets value from the product by generating their first AI summary.

Activation funnel sequence: note_created → session_started → $stt_request → note_enhanced / $ai_generation.

For the activation milestone, $ai_generation (server-side) is the strongest "user got value" signal because it confirms the summary was actually produced, not just requested.

Stage 5: Building habits (multiple meeting notes)

Goal: measure whether a user moves from first use to repeated use.

Habit signals: look for users who fire note_created or $stt_request on 3+ distinct days within their first 14 days.

Stage 6: Retention (coming back)

Goal: measure whether users return to the app over time.

Retention measurement: count distinct days with show_main_window per user per week/month. A retained user has show_main_window on multiple distinct days across weeks.

Stage 7: Conversion (trial to pro)

Goal: measure monetization.

User properties for segmentation: plan (set on trial start), trial_end_date (set on trial start).

Gap: no explicit subscription_started or payment_completed event. Conversion from trial to paid is currently inferred from the plan user property or Stripe data, not a PostHog event.

Stage 8: Retention (keep paying)

Goal: measure ongoing engagement from paying users.

No stage-specific events. Use the same product events from stages 4-6 filtered to users where plan = "pro":

Gap: no explicit subscription_cancelled or payment_failed event in PostHog. Churn detection relies on usage drop-off or Stripe webhooks outside PostHog.

Suggested PostHog funnel definition

For a single end-to-end activation funnel in PostHog:

1. download_clicked (web)
2. show_main_window (desktop)
3. user_signed_in (desktop)
4. onboarding_completed (desktop)
5. note_created (desktop)
6. $stt_request (server, optionally filter $stt_duration >= 300)
7. $ai_generation (server)

Note: steps 1→2 cannot be linked at per-user level without sign-in (see Stage 2 identity notes). Steps 2→7 are linked via machine fingerprint and Supabase user ID after sign-in.

User property catalog

PostHog user properties are set via $set, $set_once, and $identify payloads.

Telemetry controls and environment behavior

• Desktop opt-out:
  • telemetry_consent config side effect calls analyticsCommands.setDisabled(!value).
  • When disabled, desktop plugin drops event, setProperties, and identify calls.
  • Source: apps/desktop/src/shared/config/registry.ts, plugins/analytics/src/ext.rs.
• Desktop PostHog initialization:
  • Release builds require POSTHOG_API_KEY at compile time.
  • Debug builds use option_env!("POSTHOG_API_KEY"); if missing, events are not sent to PostHog (they only hit local tracing fallback).
  • Source: plugins/analytics/src/lib.rs, crates/analytics/src/lib.rs.
• Web:
  • PostHog is not initialized in dev mode.
  • Source: apps/web/src/providers/posthog.tsx.
• API:
  • PostHog client is active only in non-debug builds (production requires POSTHOG_API_KEY).
  • Source: apps/api/src/main.rs.
• Note on scope:
  • Desktop telemetry_consent only controls the desktop plugin path. No code path currently applies that toggle to server-side $stt_request / $ai_generation / trial events.

Feature flags

Feature flag checks are wired through PostHog capability in hypr_analytics, but current desktop feature strategy is hardcoded:

• Feature::Chat => FlagStrategy::Hardcoded(true)
• Source: plugins/flag/src/feature.rs.

If a feature uses FlagStrategy::Posthog(key), the check resolves via is_feature_enabled(flag_key, distinct_id) with desktop machine fingerprint as distinct ID.

How to update this document

1. Search for all emitters:
   • analyticsCommands.event(
   • analyticsCommands.setProperties(
   • analyticsCommands.identify(
   • AnalyticsPayload::builder("...)`
   • posthog.capture( / posthog.identify(
2. Verify payload keys at each callsite (watch for nested objects like properties: {...}).
3. Re-run this inventory after any analytics refactor in plugins/analytics, crates/analytics, crates/llm-proxy, crates/transcribe-proxy, or crates/api-subscription.