PostHog Analytics & Session Replay

What's Already Configured

The bootstrap includes a complete PostHog setup with:

• Session Replay - Records user sessions with privacy protections
• Automatic Screen Tracking - Tracks navigation automatically via ScreenTracker component
• Event Tracking - Ready to use via usePostHog() hook
• Privacy Controls - Text inputs and images are masked by default

Files Involved

How Session Replay Works

What Gets Recorded

• ✅ Screen views and navigation
• ✅ Touch interactions (taps, swipes)
• ✅ UI changes and animations
• ✅ Network requests (with captureNetworkTelemetry: true)
• ✅ Console logs (with captureLog: true)

Privacy Protections

• 🔒 Text inputs masked - All form inputs show as ****
• 🔒 Images masked - Photos and avatars are blurred/hidden
• 🔒 Sensitive data protected - No actual typed content recorded

Recording Behavior

• Starts automatically when app launches
• Continues throughout the session
• Stops when app is closed/backgrounded
• Each session is a separate replay in PostHog dashboard
• Data is compressed and sent in batches (not real-time)

Data Usage

• ~100-500KB per minute of usage
• Throttled to 1 second intervals (throttleDelayMs: 1000)
• Only captures visual changes, not full video

Configuration Options

All settings are in lib/posthog.ts:

Using PostHog in Your App

Track Custom Events

Import the hook and use it anywhere:

import { usePostHog } from 'posthog-react-native';

const posthog = usePostHog();

// Track an event
posthog?.capture('button_pressed', {
  button_name: 'checkout',
  screen: 'product_detail',
});

Identify Users

Set user identity (typically after login):

posthog?.identify(userId, {
  email: user.email,
  plan: 'premium',
});

Reset on Logout

Clear user identity:

posthog?.reset();

Set User Properties

Update user metadata:

posthog?.setPersonProperties({
  credits: 100,
  subscription_status: 'active',
});

Environment Variables

Required for PostHog to work:

EXPO_PUBLIC_POSTHOG_KEY=phc_your_project_key
EXPO_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

If not set, PostHog is automatically disabled with a console warning.

Rebuild Required

PostHog session replay uses native modules. After configuration changes to app.json, you must rebuild:

npx expo prebuild --clean
npx expo run:ios  # or run:android

Or with EAS:

eas build --profile development-client --platform ios

Viewing Data in PostHog

Session Replays

1. Go to PostHog → Session Replay
2. Click on a session to watch the replay
3. See timeline of events, network calls, and console logs

Events

1. Go to PostHog → Events
2. See all captured events:
   • $screen - Automatic screen views
   • $pageview - Navigation tracking
   • Custom events you capture

Users

1. Go to PostHog → Persons
2. See identified users with their properties
3. View their session history and events

Common Issues

"Waiting for events" in Dashboard

Cause: App hasn't been rebuilt after configuration changes
Fix: Run npx expo prebuild --clean and rebuild the app

No Session Replay

Cause: Session replay requires native modules to be rebuilt
Fix: Clean rebuild with npx expo prebuild --clean

Events Not Appearing

Cause: PostHog API key not set or app not rebuilt
Fix:

1. Verify EXPO_PUBLIC_POSTHOG_KEY is set in environment
2. Rebuild the app
3. Wait 1-2 minutes (there can be a delay)

Privacy Concerns

Cause: Default settings mask all inputs and images
Fix: Adjust maskAllTextInputs and maskAllImages in lib/posthog.ts if you need to see more data (consider privacy implications)

Automatic Screen Tracking

The ScreenTracker component in app/_layout.tsx automatically tracks all screen views using Expo Router's navigation hooks. No manual tracking needed for navigation.

When to Use PostHog

• Product Analytics - Understand user behavior and feature usage
• Debugging - Watch session replays to see exactly what users experienced
• Feature Flags - A/B testing and gradual rollouts (requires additional setup)
• User Feedback - Combine with support tickets to see what happened
• Conversion Funnels - Track user journeys through your app

Performance Impact

• Minimal CPU overhead (snapshots are throttled)
• Network usage: ~100-500KB per minute
• Battery impact: Negligible
• Storage: Data is sent to PostHog, not stored locally

Best Practices

1. Always mask sensitive data - Keep maskAllTextInputs: true for production
2. Track meaningful events - Don't over-track; focus on key user actions
3. Identify users after login - Enables user-specific analysis
4. Reset on logout - Prevents data leakage between users
5. Use properties - Add context to events for better analysis
6. Test in development - Verify events appear before deploying

Reference

• PostHog React Native Docs: https://posthog.com/docs/libraries/react-native
• Session Replay Docs: https://posthog.com/docs/session-replay/mobile

Source: Ampli-Group/agentic-mobile-blueprint — distributed by TomeVault.