Skip to main content
Complete setup guide: See /docs/integrations/Crashlytics.md in the project

​
What is Crashlytics?

Crash Reports

Automatic crash detection with stack traces

Error Tracking

Non-fatal errors and custom logging

User Privacy

GDPR compliant with user consent toggle

Free Tier

Unlimited reports on Firebase free tier
Users rarely report crashes. Without crash reporting, you are flying blind. Crashlytics captures every crash with full context so you can fix issues before they tank your App Store ratings.

​
Step-by-Step Setup

1

Step 1: Go to Firebase Console

Navigate to the Firebase Console and create a new project or select an existing one.
2

Step 2: Name Your Project

Give your Firebase project a name. This will be your crash reporting dashboard for monitoring your iOS app.
3

Step 3: Disable Analytics (Optional)

For now, you can disable Google Analytics. You can always enable it later if needed. Crashlytics works independently.
4

Step 4: Add iOS App

Click Add app and select the iOS platform. This will start the iOS app registration process.
5

Step 5: Register Your App

Enter your iOS bundle identifier. Make sure it matches exactly with your Xcode project bundle ID.
6

Step 6: Download GoogleService-Info.plist

Download the GoogleService-Info.plist file. Add it to your Xcode project root and make sure it’s added to your target.
  • ✅ Check “Copy items if needed”
  • ✅ Select your app target
7

Step 7: Add Firebase SDK

Add the Firebase SDK to your project. We recommend using Swift Package Manager (SPM) for easier dependency management.
8

Step 8: Add via Swift Package Manager

In Xcode, go to File → Add Packages. Enter the Firebase iOS SDK URL:
https://github.com/firebase/firebase-ios-sdk
Select the FirebaseCrashlytics package.
9

Step 9: Add Initialization Code

Add Firebase initialization code to your App.swift or AppDelegate:
import Firebase

// In your App init or AppDelegate
FirebaseApp.configure()
10

Step 10: Add Linker Flags

In Build Settings, add -ObjC to Other Linker Flags. This is required for Firebase to work correctly with Swift.
11

Step 11: Add Run Script Phase

Add a new Run Script phase in Build Phases:
  1. Click + → New Run Script Phase
  2. Name it “Upload dSYMs to Crashlytics”
  3. Add the upload script (see Firebase docs)
12

Step 12: Configure Input Files

Add the required input files to the run script phase:
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
$(SRCROOT)/$(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)
13

Step 13: Complete Run Script Setup

Verify your run script phase is configured correctly with both the script and input files. This ensures crash reports are properly symbolicated.
14

Step 14: Set Debug Information Format

In Build Settings, set Debug Information Format to DWARF with dSYM File for Release builds. This generates the debug symbols needed for crash reports.
15

Step 15: Add Test Crash Code

Add a test crash button to verify Crashlytics is working:
#if DEBUG
Button("Test Crash") {
    fatalError("Test crash for Firebase")
}
#endif
16

Step 16: Test on Real Device

Run your app on a real device (not simulator) and trigger the test crash. Relaunch the app to send the crash report to Firebase.
Crashlytics does not work reliably in the simulator. Always test on a real device.
17

Step 17: Verify in Dashboard

Check your Firebase Crashlytics dashboard. You should see the test crash appear (may take a few minutes).
Remember to remove the test crash code before submitting to the App Store!

​
How It Works

​
Automatic Integration

The boilerplate includes a CrashReporter protocol that automatically switches between Firebase Crashlytics and NoOp based on availability: 
// From CompositionRoot.swift (automatic)
if FeatureFlags.crashlyticsEnabled && GoogleService-Info.plist exists {
    crashReporter = CrashlyticsCrashReporter()  // Real tracking
} else {
    crashReporter = NoOpCrashReporter()         // No tracking
}
No code changes needed! Just add the plist file.

​
User Privacy

Users control crash reporting in Settings → Share Diagnostics:
  • ✅ ON → Crashes sent to Firebase
  • ❌ OFF → No data sent
GDPR Compliant:
  • Never sends email addresses
  • User has opt-out control
  • Clear privacy disclosure

​
What Gets Tracked

​
Automatically

  • Crash reports with stack traces
  • Device info (model, iOS version)
  • App version
  • User ID (anonymized, no email)
  • Session info

​
Custom (Optional)

  • Non-fatal errors
  • Custom logs/breadcrumbs
  • User attributes (subscription tier, theme, etc.)

​
Viewing Reports

Firebase Console:
  1. Go to Firebase Console
  2. Select your project
  3. Crashlytics (in sidebar)
  4. View crashes, errors, logs
Reports include:
  • Stack traces
  • Device information
  • User ID
  • App version
  • Custom logs

​
Cost

Firebase Free Tier:
  • ✅ Unlimited crash reports
  • ✅ 30-day retention
  • ✅ Basic analytics
  • ✅ Enough for most apps
Blaze Plan (optional):
  • Extended retention
  • More features
  • Pay as you go (very low cost)

​
Troubleshooting

  • Make sure you tested on a real device, not simulator
  • Relaunch the app after the crash to send the report
  • Wait a few minutes for the report to appear
  • Check that GoogleService-Info.plist is in your target
  • Verify dSYM upload script is running
  • Check that Debug Information Format is set to DWARF with dSYM File
  • Ensure input files are configured correctly
  • Make sure -ObjC is in Other Linker Flags
  • Clean build folder (⌘⇧K) and rebuild
  • Check that you only added FirebaseCrashlytics package

Full Integration Guide

See complete details in /docs/integrations/Crashlytics.md

Feature Flags

Configure in Composition/FeatureFlags.swift

Settings Module

User consent toggle

Privacy Policy

Update Resources/privacy.md to mention crash reporting

​
Need Help?

The boilerplate handles all the integration automatically. You just need to:
  1. Add GoogleService-Info.plist
  2. Enable feature flag
  3. Build and run
If you have issues, check the troubleshooting section above or in /docs/integrations/Crashlytics.md.