> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crashlytics Setup

> Add Firebase Crashlytics to track crashes and errors in production.

<Info>
  **Complete setup guide:** See `/docs/integrations/Crashlytics.md` in the project
</Info>

## What is Crashlytics?

<CardGroup cols={2}>
  <Card title="Crash Reports" icon="bug">
    Automatic crash detection with stack traces
  </Card>

  <Card title="Error Tracking" icon="triangle-exclamation">
    Non-fatal errors and custom logging
  </Card>

  <Card title="User Privacy" icon="shield">
    GDPR compliant with user consent toggle
  </Card>

  <Card title="Free Tier" icon="dollar">
    Unlimited reports on Firebase free tier
  </Card>
</CardGroup>

<Warning>
  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.
</Warning>

## Step-by-Step Setup

<Steps>
  <Step title="Step 1: Go to Firebase Console">
    Navigate to the [Firebase Console](https://console.firebase.google.com) and create a new project or select an existing one.
  </Step>

  <Step title="Step 2: Name Your Project">
    Give your Firebase project a name. This will be your crash reporting dashboard for monitoring your iOS app.
  </Step>

  <Step title="Step 3: Disable Analytics (Optional)">
    For now, you can disable Google Analytics. You can always enable it later if needed. Crashlytics works independently.
  </Step>

  <Step title="Step 4: Add iOS App">
    Click **Add app** and select the iOS platform. This will start the iOS app registration process.
  </Step>

  <Step title="Step 5: Register Your App">
    Enter your iOS bundle identifier. Make sure it matches exactly with your Xcode project bundle ID.
  </Step>

  <Step title="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>

  <Step title="Step 7: Add Firebase SDK">
    Add the Firebase SDK to your project. We recommend using Swift Package Manager (SPM) for easier dependency management.
  </Step>

  <Step title="Step 8: Add via Swift Package Manager">
    In Xcode, go to **File → Add Packages**. Enter the Firebase iOS SDK URL:

    ```text theme={null}
    https://github.com/firebase/firebase-ios-sdk
    ```

    Select the **FirebaseCrashlytics** package.
  </Step>

  <Step title="Step 9: Add Initialization Code">
    Add Firebase initialization code to your `App.swift` or `AppDelegate`:

    ```swift theme={null}
    import Firebase

    // In your App init or AppDelegate
    FirebaseApp.configure()
    ```
  </Step>

  <Step title="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>

  <Step title="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)
  </Step>

  <Step title="Step 12: Configure Input Files">
    Add the required input files to the run script phase:

    ```text theme={null}
    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
    $(SRCROOT)/$(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)
    ```
  </Step>

  <Step title="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>

  <Step title="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>

  <Step title="Step 15: Add Test Crash Code">
    Add a test crash button to verify Crashlytics is working:

    ```swift theme={null}
    #if DEBUG
    Button("Test Crash") {
        fatalError("Test crash for Firebase")
    }
    #endif
    ```
  </Step>

  <Step title="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.

    <Warning>
      Crashlytics does not work reliably in the simulator. Always test on a real device.
    </Warning>
  </Step>

  <Step title="Step 17: Verify in Dashboard">
    Check your Firebase Crashlytics dashboard. You should see the test crash appear (may take a few minutes).

    <Note>
      Remember to **remove the test crash code** before submitting to the App Store!
    </Note>
  </Step>
</Steps>

## How It Works

### Automatic Integration

The boilerplate includes a **CrashReporter protocol** that automatically switches between Firebase Crashlytics and NoOp based on availability:

```swift theme={null}
// 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:**

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup cols={2}>
  <Card title="Full Integration Guide" icon="book">
    See complete details in `/docs/integrations/Crashlytics.md`
  </Card>

  <Card title="Feature Flags" icon="flag">
    Configure in `Composition/FeatureFlags.swift`
  </Card>

  <Card title="Settings Module" icon="gear" href="/pages/modules/feature-settings">
    User consent toggle
  </Card>

  <Card title="Privacy Policy" icon="shield">
    Update `Resources/privacy.md` to mention crash reporting
  </Card>
</CardGroup>

## 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`.