Skip to main content

Retention, Measurement & LTV Strategy

Status: Proposed 2026-09-23 — specification complete; implementation not started

TrickBook's immediate product problem is no longer only acquisition. Available production checkpoints grew from 326 users on September 11 to 354 on September 23: 28 net new accounts, or 8.6%. The stronger measured week had 16 new users versus 7 in the prior week, while weekly active users moved from 5 to 7. Website pageviews rose 9%, but App Store clicks fell from 5 to 1. Event pages became the largest site section, and one Malibu event produced 73% of identified Google traffic. Reach is improving faster than our ability to explain activation, retention, or conversion.

This specification defines the system needed to answer four questions before we optimize monetization:

  1. Which product behaviors create durable rider value?
  2. Which acquisition sources and app versions retain those riders?
  3. Can every supported client receive the correct update policy safely?
  4. When is there enough evidence to meter AI without damaging the free habit?

Product principles​

  • Core progression remains free. Trick tracking, attempts, landings, spots, events, profiles, posting, and social participation are the habit loop.
  • Meter marginal cost, not belonging. AI voice/video analysis and advanced coaching are the natural paid layer because usage has measurable COGS.
  • Measure before redesigning. Instrument flows before changing onboarding, Spots, Events, or companions.
  • Cohorts beat totals. Aggregate signups can rise while retention falls.
  • Server decisions are authoritative. Version policy, entitlements, wallet debits, and accepted analytics events cannot depend on client claims alone.
  • No dark patterns. Update prompts are proportional, paywalls state the benefit and price, and analytics collection follows consent and deletion rules.

North-star and metric hierarchy​

The north-star metric is Weekly Progressing Riders (WPR): distinct riders who complete at least one meaningful action during a rolling seven-day window. A meaningful action is one of:

  • add a trick, log an attempt, or record a landing;
  • save an event or spot, add an event to a calendar, or open directions;
  • complete a substantive AI coaching interaction;
  • create a post/comment or form a rider connection.

Supporting metrics:

  • Activation: first meaningful action within 48 hours of registration.
  • Time to value: registration to first meaningful action, p50/p90.
  • Retention: D1, D7, D14, D30, and rolling W4 retention.
  • Depth: meaningful actions per progressing rider per week.
  • Breadth: number of distinct value domains used per retained rider.
  • AI economics: cost, replies, completion rate, and retained-user lift.
  • Version health: active devices by version/build and update conversion.
  • Revenue: trial start, paid conversion, ARPPU, churn, gross margin, and LTV.

active must never mean merely opening the app. WPR is the strategic metric; DAU/MAU remains diagnostic.

Measurement update, 2026-10-06​

What the backend computes today, so the dashboard numbers can be read correctly:

  • Windows are weekly, not exact-day. A rider counts as retained in W1 if any meaningful action falls on days 1 to 7 after signup, W2 for days 8 to 14, W3 for 15 to 21, W4 for 22 to 28. A window is eligible only once it has fully elapsed. At the current scale an exact-day window reads zero by arithmetic, not behaviour.
  • Weekly Progressing Riders is served by GET /api/analytics/dashboard/wpr: distinct riders with at least one meaningful action per rolling seven-day window, with depth (actions per rider).
  • Exclusions. Accounts with role: admin, isBot: true or analyticsExcluded: true are left out of every metric and counted in the response's excluded field. Set analyticsExcluded by hand for QA and App Review accounts; the events stay in the collection.
  • Signups. Email signups are tracked by the clients; Google and Apple signups are recorded server-side when the sign-in creates the account, since a client cannot tell a first sign-in from a returning one.
  • Event names must match the meaningful list exactly; the web calendar event was renamed to event_calendar_added so it counts.
  • Error tracking is Sentry behind SENTRY_DSN on the API, NEXT_PUBLIC_SENTRY_DSN on the website and EXPO_PUBLIC_SENTRY_DSN on mobile; nothing loads until a DSN is set, and native crash capture on mobile needs the next EAS build.

Canonical event contract​

Every event uses a client-generated UUID and this envelope:

{
  "eventId": "uuid-v7",
  "name": "trick_attempt_logged",
  "occurredAt": "2026-09-23T18:00:00.000Z",
  "receivedAt": "server-assigned",
  "anonymousId": "installation-scoped-id",
  "userId": "nullable-before-auth",
  "sessionId": "uuid",
  "platform": "ios|android|web",
  "appVersion": "3.2.0",
  "buildNumber": 18,
  "schemaVersion": 1,
  "source": {
    "firstTouch": "google|instagram|direct|referral|other",
    "utmSource": "nullable",
    "landingPath": "/events/..."
  },
  "properties": {}
}

Required rules:

  • eventId has a unique database index; retrying is idempotent.
  • occurredAt is client time, while receivedAt is trusted server time.
  • Events are append-only. Corrections are new events, never silent mutations.
  • Known users are identified across devices; anonymous history is aliased once at authentication without rewriting raw events.
  • Event properties use IDs and bounded enums, not names, email, free text, raw prompts, exact location, or media contents.
  • Schema versions are validated server-side. Unknown names/properties are quarantined rather than contaminating production metrics.
  • Internal staff, bots, App Review, and automated QA are labeled and excluded by default, never deleted from the underlying evidence.

Initial taxonomy​

Lifecycle: app_installed, app_opened, signup_completed, onboarding_started, onboarding_completed, session_ended.

Progression: trick_viewed, trick_added, trick_attempt_logged, trick_landed, progression_status_changed.

Discovery: spot_viewed, spot_saved, spot_directions_opened, event_viewed, event_saved, event_calendar_added, event_shared.

AI: ai_session_started, ai_response_completed, ai_session_completed, ai_allowance_exhausted. Store model, latency, token/character counts, and cost micros—never prompt text in analytics.

Community: post_created, comment_created, rider_followed, homie_connected.

Notifications: notification_permission_result, notification_received, notification_opened, with category/campaign IDs.

Versioning: version_heartbeat, update_prompt_seen, update_prompt_dismissed, update_store_opened, update_completed.

Revenue: paywall_viewed, checkout_started, trial_started, subscription_started, subscription_renewed, subscription_canceled, subscription_expired, ai_credit_debited. Store receipts/webhooks remain the financial source of truth; analytics events do not grant entitlements.

Feature-value analysis​

Assign every meaningful event to a value domain: progression, discovery, coaching, or community. For each signup cohort, compare D7/D30 retention by:

  • first value domain and first meaningful event;
  • acquisition source and first landing page;
  • sport, platform, app version/build, and onboarding variant;
  • number of value domains reached in the first 48 hours;
  • AI users versus propensity-matched non-AI users.

Do not call correlation causation. Use cohort findings to choose a hypothesis, then randomized feature flags to test it. Every experiment needs one primary metric, guardrails, exposure events, minimum run time, and a written stopping rule before launch.

Version inventory and update policy​

The existing push-token record accepts appVersion, but that is incomplete: it sees only registered tokens and becomes stale. Add an authenticated or anonymous POST /api/client-heartbeat on launch/resume with installation ID, platform, semantic version, build number, OS/device family, locale, timezone, first-seen, last-seen, and notification capability. Upsert one current record per installation; retain version transitions separately.

GET /api/mobile/version-policy?platform=ios returns a signed/configured policy:

{
  "latestVersion": "3.2.0",
  "minimumSupportedVersion": "3.1.0",
  "promptMode": "optional|required",
  "title": "A new TrickBook is ready",
  "message": "Release-specific plain text",
  "storeUrl": "platform-specific URL",
  "effectiveAt": "2026-09-23T18:00:00Z",
  "gracePeriodHours": 24,
  "policyRevision": 7
}
  • Current: no prompt.
  • Below latest but at/above minimum: dismissible prompt, frequency-capped.
  • Below minimum: blocking prompt after effectiveAt plus grace period.
  • Never interrupt onboarding, media upload, payment, an active coaching response, or an unsaved attempt. Apply a required prompt at the next safe point.
  • Cache the last valid policy. If the policy endpoint fails, do not convert an optional update into a required one. Emergency blocks require a cached, unexpired signed policy.
  • Admin changes require reason, actor, timestamp, and immutable audit history.

Dashboard slices: active installations by version over 1/7/30 days, update prompt funnel, retention/crash rate by build, and unsupported-client attempts.

Retention interventions​

Interventions are triggered by demonstrated intent, not generic blasts:

  • Incomplete onboarding: resume the next unfinished choice.
  • First trick saved but no attempt: reminder tied to that trick and preferred riding window.
  • Attempt without landing: progression tip or prerequisite, not a sales prompt.
  • Event saved: time-sensitive reminder with calendar/location action.
  • Former weekly rider inactive 7 days: recap progress and suggest one achievable next action.
  • AI allowance nearing exhaustion: show remaining value and cost before use; paywall only when intent is clear.

Frequency caps, quiet hours, per-category preferences, unsubscribe, minors' protections, and notification received/opened attribution are required.

LTV model and monetization gate​

Until paid cohorts mature, use a leading value model:

Expected LTV = expected retained paid months × monthly gross margin
Monthly gross margin = recognized revenue − store fees − AI variable cost

Report realized LTV only from revenue/expense facts. A separate LTV potential score may rank cohorts using retained weeks, meaningful-action depth, and premium-feature affinity, but it must never be labeled dollars.

AI monetization proceeds only when four gates are satisfied:

  1. reliable D7/D30 cohorts and event completeness are available;
  2. AI cost per active user and per completed outcome is measured;
  3. repeated demand and allowance exhaustion are observed;
  4. an experiment shows the proposed allowance/paywall does not materially harm activation or retained core usage.

Free core actions never debit AI credits. Server-side atomic debit precedes paid work, retries are idempotent, and failed generation refunds or never settles the reservation. Stripe/RevenueCat webhooks grant entitlements idempotently.

Data model and ownership​

  • client_installations: latest version/device heartbeat per installation.
  • client_version_history: append-only version transitions.
  • mobile_version_policies: revisioned platform policies and audit metadata.
  • analytics_events: immutable validated event envelopes, unique eventId.
  • analytics_quarantine: rejected schema versions/names with safe diagnostics.
  • experiment_exposures: stable assignment, variant, eligibility, exposure time.
  • usage_events: billable AI reservations/debits/refunds and unit cost.
  • Existing subscription/wallet records remain canonical for entitlement.

The backend owns validation, deduplication, policy, entitlement, and cost facts. Clients own capture timing and presentation. PostHog is an analysis sink, not the canonical ledger; the backend event store can forward a privacy-safe projection.

Privacy, security, and quality gates​

  • Update privacy disclosures before production collection; honor consent by region/platform and support export/deletion.
  • Avoid sensitive free text, exact coordinates, raw media, authentication data, and payment data in analytics.
  • Authenticate user-bound events but accept bounded anonymous lifecycle events with abuse controls.
  • Rate-limit ingestion, cap batch/event sizes, validate enums and timestamps, and redact logs.
  • Monitor ingest acceptance, quarantine rate, event lag, duplicates, missing identity/version dimensions, dashboard freshness, and cost drift.
  • CI contract tests compare mobile/web event payloads to the shared schema.

Delivery plan​

  1. Foundation: shared schema registry, ingestion idempotency, heartbeat, version-policy endpoint, privacy review.
  2. Mobile control: SDK instrumentation, safe-point update UI, installation identity, offline queue and retry.
  3. Value measurement: WPR and activation definitions, cohort jobs/dashboards, source attribution, internal-user filtering.
  4. Retention tests: onboarding and intent-based reminder experiments.
  5. Monetization evidence: AI cost/outcome metering, allowance experiment, then soft Pro conversion if gates pass.

Acceptance criteria​

  • At least 98% of authenticated mobile events contain platform, semantic version, build, session, and user/installation identity.
  • Duplicate delivery never increments an aggregate twice.
  • Current, optional-update, and required-update clients follow the defined policy; unsupported clients cannot start new core/premium mutations after the safe point.
  • Core actions cannot debit AI credits; premium work cannot run without an atomic entitlement or credit reservation.
  • D1/D7/D14/D30 cohorts can be reproduced from raw accepted events.
  • Every dashboard states its definition, exclusions, event-time/receive-time rule, timezone, and freshness.
  • All implementation PRs link back to this specification and the formal model.

See Formal Specification and Verification Results.