Version: 0.8.0 Platform: iOS, Android, Electron, Web

This guide explains how to set up Firebase Analytics and Sentry for the nChat mobile and desktop apps.

1. Prerequisites
2. Firebase Setup
3. Sentry Setup
4. iOS Configuration
5. Android Configuration
6. Electron Configuration
7. Environment Variables
8. Testing
9. Troubleshooting

• Firebase project created
• Sentry account created
• Node.js 20+ installed
• iOS: Xcode 15+ and CocoaPods
• Android: Android Studio and JDK 17

1. Go to Firebase Console
2. Click "Add project"
3. Enter project name: nchat-production (or your preferred name)
4. Enable Google Analytics (recommended)
5. Choose or create Analytics account
6. Click "Create project"

In Firebase Console:

1. Analytics: Enabled by default
2. Crashlytics:
   • Go to Crashlytics in left menu
   • Click "Enable Crashlytics"
3. Performance Monitoring:
   • Go to Performance in left menu
   • Click "Get started"
4. Remote Config (optional):
   • Go to Remote Config
   • Click "Create configuration"

1. Click "Add app" → iOS
2. Enter iOS Bundle ID: com.nself.nchat
3. Enter App nickname: nChat iOS
4. Download GoogleService-Info.plist
5. Save to: platforms/capacitor/ios/App/App/GoogleService-Info.plist

1. Click "Add app" → Android
2. Enter package name: io.nself.chat
3. Enter App nickname: nChat Android
4. Download google-services.json
5. Save to: platforms/capacitor/android/app/google-services.json

1. Click "Add app" → Web
2. Enter App nickname: nChat Web
3. Copy Firebase config object
4. Add to .env.local:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

1. Go to Sentry.io
2. Click "Create Project"
3. Select platform: "React Native" (for mobile) or "Electron" (for desktop)
4. Enter project name: nchat-mobile or nchat-desktop
5. Copy the DSN

For better organization, create separate projects:

• nchat-ios
• nchat-android
• nchat-electron
• nchat-web

1. Go to Settings → Account → API → Auth Tokens
2. Click "Create New Token"
3. Scopes required:
   • project:releases
   • project:write
   • org:read
4. Copy the token
5. Add to sentry.properties

cd platforms/capacitor/ios/App
pod install

1. Open platforms/capacitor/ios/App/App.xcworkspace in Xcode
2. Right-click on "App" folder
3. Add Files to "App"
4. Select GoogleService-Info.plist
5. Ensure "Copy items if needed" is checked
6. Add to "App" target

Edit platforms/capacitor/ios/App/App/Info.plist:

<key>SentryDSN</key>
<string>YOUR_SENTRY_DSN</string>

Edit platforms/capacitor/ios/App/Podfile:

# Firebase
pod 'Firebase/Analytics'
pod 'Firebase/Crashlytics'
pod 'Firebase/Performance'

# Sentry
pod 'Sentry', :git => 'https://github.com/getsentry/sentry-cocoa.git', :tag => '8.17.2'

Then run:

pod install

In Xcode:

1. Select "App" target
2. Build Phases → Add "Run Script"
3. Add Firebase Crashlytics script:

"${PODS_ROOT}/FirebaseCrashlytics/run"

4. Add Sentry upload script:

export SENTRY_PROPERTIES=../sentry.properties
"${PODS_ROOT}/../../node_modules/@sentry/cli/bin/sentry-cli" upload-dif "$DWARF_DSYM_FOLDER_PATH"

Copy google-services.json to:

platforms/capacitor/android/app/google-services.json

The build.gradle is already configured with:

• Firebase plugins
• Sentry plugin
• Required dependencies

Create platforms/capacitor/android/sentry.properties:

defaults.url=https://sentry.io/
defaults.org=YOUR_SENTRY_ORG
defaults.project=nchat-android
auth.token=YOUR_SENTRY_AUTH_TOKEN

If using ProGuard, add to platforms/capacitor/android/app/proguard-rules.pro:

# Firebase
-keep class com.google.firebase.** { *; }
-keep class com.google.android.gms.** { *; }

# Sentry
-keepattributes LineNumberTable,SourceFile
-dontwarn org.slf4j.**
-dontwarn javax.**
-keep class io.sentry.** { *; }

npm install @sentry/electron

Create platforms/electron/main/sentry.ts:

import * as Sentry from '@sentry/electron/main'

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  release: `nchat@${process.env.APP_VERSION}`,
  tracesSampleRate: 0.2,
})

// At the top
require('./main/sentry')

// Rest of your code

Create .env.local in project root:

# Firebase (Web)
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

# Sentry
NEXT_PUBLIC_SENTRY_DSN=your_sentry_dsn
NEXT_PUBLIC_SENTRY_ORG=your_sentry_org
NEXT_PUBLIC_SENTRY_PROJECT=nchat
SENTRY_AUTH_TOKEN=your_auth_token

# Analytics
NEXT_PUBLIC_ANALYTICS_ENABLED=true
NEXT_PUBLIC_RELEASE_VERSION=0.8.0

# Performance
NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0.1
NEXT_PUBLIC_SENTRY_REPLAYS_SAMPLE_RATE=0.1

Create src/lib/analytics/init.ts:

import { initializeAnalytics } from '@/lib/analytics'

export async function initAnalytics() {
  await initializeAnalytics({
    enabled: process.env.NEXT_PUBLIC_ANALYTICS_ENABLED === 'true',
    providers: ['firebase', 'sentry'],
  })
}

In src/app/layout.tsx or main app component:

import { initAnalytics } from '@/lib/analytics/init'

useEffect(() => {
  initAnalytics()
}, [])

iOS:

1. In Xcode, Edit Scheme → Run → Arguments
2. Add argument: -FIRDebugEnabled

Android:

adb shell setprop debug.firebase.analytics.app io.nself.chat

Firebase:

1. Open Firebase Console
2. Go to Analytics → DebugView
3. Should see events in real-time

Sentry:

1. Open Sentry dashboard
2. Go to Issues
3. Trigger a test error:

import { sentryMobile } from '@/lib/analytics/sentry-mobile'

sentryMobile.captureMessage('Test message', 'info')

iOS:

fatalError("Test crash")

Android:

throw RuntimeException("Test crash")

Should appear in Firebase Crashlytics and Sentry within a few minutes.

Issue: Events not appearing in Firebase Console

Solutions:

1. Check GoogleService-Info.plist / google-services.json is correctly placed
2. Verify app is in debug mode
3. Wait up to 24 hours for production data
4. Check DebugView for real-time events

Issue: Errors not appearing in Sentry

Solutions:

1. Verify DSN is correct
2. Check network connectivity
3. Ensure Sentry is initialized before errors occur
4. Check beforeSend filter isn't blocking events

Issue: Build fails with Firebase/Sentry errors

Solutions:

cd platforms/capacitor/ios/App
pod deintegrate
pod install

Issue: Build fails with Firebase/Sentry errors

Solutions:

cd platforms/capacitor/android
./gradlew clean
./gradlew build --refresh-dependencies

Issue: User consent resets on app restart

Solutions:

1. Check localStorage permissions
2. Verify Capacitor Preferences plugin is installed
3. Check for errors in console

• Always request consent before tracking
• Provide granular controls
• Respect user choices
• Be transparent about data collection

• Sample performance data (don't track 100%)
• Use appropriate sample rates:
  • Production: 0.1 (10%)
  • Staging: 0.5 (50%)
  • Development: 1.0 (100%)

• Filter sensitive data from error reports
• Don't send passwords, tokens, API keys
• Scrub PII from breadcrumbs

• Use consistent naming conventions
• Follow Firebase event naming rules:
  • Lowercase with underscores
  • Max 40 characters
  • No spaces or special characters

• Test on real devices, not just simulators
• Test in different network conditions
• Test opt-out functionality
• Test data export/deletion

• Firebase Analytics Docs
• Sentry React Native Docs
• Capacitor Firebase Plugin
• Privacy Policy Template

For issues:

1. Check Common Issues
2. Search GitHub issues
3. Contact: [email protected]