Crashlytics Setup

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

Step 1: Go to Firebase Console

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

Step 2: Name Your Project

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

Step 3: Disable Analytics (Optional)

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

Step 4: Add iOS App

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

Step 5: Register Your App

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

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

Step 7: Add Firebase SDK

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

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.

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()

Step 10: Add Linker Flags

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

Step 11: Add Run Script Phase

Add a new Run Script phase in Build Phases:

Click + → New Run Script Phase
Name it “Upload dSYMs to Crashlytics”
Add the upload script (see Firebase docs)

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)

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.

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.

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

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.

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)
// checkCrashlyticsAvailable() returns true when GoogleService-Info.plist is bundled
if FeatureFlags.crashlyticsEnabled && Self.checkCrashlyticsAvailable() {
    self.crashReporter = CrashlyticsCrashReporter()  // Real tracking
} else {
    self.crashReporter = NoOpCrashReporter()         // No tracking
}

crashlyticsEnabled is off in DEBUG and reads the CRASHLYTICS_ENABLED environment variable in Release (FeatureFlags.swift). Add the plist and flip the flag — no other code changes needed.

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:

Go to Firebase Console
Select your project
Crashlytics (in sidebar)
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

Crashes not appearing in dashboard

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

Symbolication not working

Verify dSYM upload script is running
Check that Debug Information Format is set to DWARF with dSYM File
Ensure input files are configured correctly

Build errors after adding Firebase

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:

Add GoogleService-Info.plist
Enable feature flag
Build and run

If you have issues, check the troubleshooting section above or in /docs/integrations/Crashlytics.md.

Getting Started

Setup Guides

Core Modules

Feature Modules

Migration

Reference

Before You Submit

What is Crashlytics?

Crash Reports

Error Tracking

User Privacy

Free Tier

Step-by-Step Setup

How It Works

Automatic Integration

User Privacy

What Gets Tracked

Automatically

Custom (Optional)

Viewing Reports

Cost

Troubleshooting

Full Integration Guide

Feature Flags

Settings Module

Privacy Policy

Need Help?

​What is Crashlytics?

Crash Reports

Error Tracking

User Privacy

Free Tier

​Step-by-Step Setup

​How It Works

​Automatic Integration

​User Privacy

​What Gets Tracked

​Automatically

​Custom (Optional)

​Viewing Reports

​Cost

​Troubleshooting

​Related Guides

Full Integration Guide

Feature Flags

Settings Module

Privacy Policy

​Need Help?

What is Crashlytics?

Step-by-Step Setup

How It Works

Automatic Integration

User Privacy

What Gets Tracked

Automatically

Custom (Optional)

Viewing Reports

Cost

Troubleshooting

Related Guides

Need Help?