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

# Firebase Setup

> Configure Firebase for analytics, crashlytics, and authentication

## Prerequisites

* Google account
* Completed [App Identity](/configuration/app-identity) configuration
* Bundle identifiers finalized (cannot change after setup)

## Create Firebase Project

1. Go to [Firebase Console](https://console.firebase.google.com/)

2. Click **Add project** or **Create a project**

3. Enter your project name (e.g., "My App")

4. Configure Google Analytics (recommended):
   * Enable Google Analytics
   * Select or create an Analytics account
   * Accept terms and conditions

5. Click **Create project**

6. Wait for project creation to complete

## Add iOS App to Firebase

### 1. Register iOS App

1. In Firebase Console, click the iOS icon or **Add app**

2. Enter your iOS bundle ID:
   * Must match `ios.bundleIdentifier` in `app.json`
   * Example: `com.yourcompany.yourapp`

3. Enter app nickname (optional): "My App iOS"

4. Enter App Store ID (optional, can add later)

5. Click **Register app**

### 2. Download Config File

1. Download `GoogleService-Info.plist`

2. Save it to your project:

   ```
   apps/mobile/GoogleService-Info.plist
   ```

3. **Important**: Add to `.gitignore` if it contains sensitive data:
   ```
   # .gitignore
   apps/mobile/GoogleService-Info.plist
   ```

### 3. Verify Configuration

Ensure `app.json` references the file:

```json theme={null}
{
  "expo": {
    "ios": {
      "googleServicesFile": "./GoogleService-Info.plist"
    }
  }
}
```

### 4. Skip SDK Installation

Click **Next** through the SDK installation steps - React Native Firebase is already configured in the starter.

## Add Android App to Firebase

### 1. Register Android App

1. In Firebase Console, click the Android icon or **Add app**

2. Enter your Android package name:
   * Must match `android.package` in `app.json`
   * Example: `com.yourcompany.yourapp`

3. Enter app nickname (optional): "My App Android"

4. Enter SHA-1 signing certificate (optional for now)

5. Click **Register app**

### 2. Download Config File

1. Download `google-services.json`

2. Save it to your project:

   ```
   apps/mobile/google-services.json
   ```

3. **Important**: Add to `.gitignore` if it contains sensitive data:
   ```
   # .gitignore
   apps/mobile/google-services.json
   ```

### 3. Verify Configuration

Ensure `app.json` references the file:

```json theme={null}
{
  "expo": {
    "android": {
      "googleServicesFile": "./google-services.json"
    }
  }
}
```

### 4. Skip SDK Installation

Click **Next** through the SDK installation steps - React Native Firebase is already configured.

## Enable Firebase Services

### Firebase Analytics

Analytics is enabled by default. To verify:

1. In Firebase Console, go to **Analytics** → **Dashboard**
2. You should see "Analytics is enabled"

### Firebase Crashlytics

1. In Firebase Console, go to **Crashlytics**
2. Click **Enable Crashlytics**
3. Follow the setup wizard

### Firebase Authentication

1. In Firebase Console, go to **Authentication**
2. Click **Get started**
3. Enable sign-in methods you want to use:
   * **Email/Password**: For email-based authentication
   * **Google**: For Google Sign-In
   * **Apple**: For Sign in with Apple (required for iOS)
   * **Anonymous**: For anonymous authentication

## Configure Environment Variables

Add Firebase configuration to your `.env` file:

```bash theme={null}
# Firebase Configuration
EXPO_PUBLIC_FIREBASE_API_KEY=your-api-key
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
EXPO_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
EXPO_PUBLIC_FIREBASE_APP_ID=your-app-id
```

Find these values in Firebase Console:

1. Go to **Project Settings** (gear icon)
2. Scroll to **Your apps**
3. Select your iOS or Android app
4. Copy the configuration values

## Enable Firebase Adapter

Update `amisi.config.json` to use Firebase adapters:

```json theme={null}
{
  "auth": {
    "adapter": "firebase"
  }
}
```

Enable analytics and crash reporting in feature flags:

Edit `packages/config/src/flags.ts`:

```typescript theme={null}
const productionFlags: FeatureFlags = {
  enableAnalytics: true,
  enableCrashReporting: true,
  // ... other flags
};
```

## Test Firebase Integration

### 1. Rebuild Native Projects

Firebase requires native configuration:

```bash theme={null}
bun run clear
bun run prebuild
```

### 2. Run the App

```bash theme={null}
bun run ios
# or
bun run android
```

### 3. Verify Analytics

1. Navigate through your app
2. In Firebase Console, go to **Analytics** → **DebugView**
3. Enable debug mode on your device:

**iOS Simulator:**

```bash theme={null}
# Add to Xcode scheme arguments
-FIRDebugEnabled
```

**Android:**

```bash theme={null}
adb shell setprop debug.firebase.analytics.app com.yourcompany.yourapp
```

4. You should see events in DebugView within a few minutes

### 4. Verify Crashlytics

1. Trigger a test crash in your app
2. In Firebase Console, go to **Crashlytics**
3. You should see the crash report within a few minutes

### 5. Verify Authentication

1. Try signing in with your configured method
2. In Firebase Console, go to **Authentication** → **Users**
3. You should see the new user

## Production Setup

### iOS App Store

For production iOS builds:

1. **Add App Store ID** to Firebase:
   * Go to Firebase Console → Project Settings
   * Under iOS apps, add your App Store ID

2. **Configure App Store Connect**:
   * Ensure bundle ID matches Firebase configuration
   * Add GoogleService-Info.plist to your Xcode project (done automatically by prebuild)

### Android Play Store

For production Android builds:

1. **Add SHA-1 certificate**:

   ```bash theme={null}
   # Get SHA-1 from your keystore
   keytool -list -v -keystore your-keystore.jks -alias your-key-alias
   ```

2. **Add to Firebase**:
   * Go to Firebase Console → Project Settings
   * Under Android apps, add SHA-1 fingerprint

3. **Configure Play Store**:
   * Ensure package name matches Firebase configuration
   * Upload google-services.json with your build

## Security Best Practices

### 1. Restrict API Keys

In Firebase Console:

1. Go to **Google Cloud Console** → **APIs & Services** → **Credentials**
2. Find your API keys
3. Add restrictions:
   * **iOS**: Restrict to iOS bundle ID
   * **Android**: Restrict to Android package name and SHA-1

### 2. Configure App Check

Enable App Check for additional security:

1. In Firebase Console, go to **App Check**
2. Register your apps
3. Configure attestation providers

### 3. Set Security Rules

Configure Firestore and Storage security rules:

1. Go to **Firestore Database** → **Rules**
2. Set appropriate read/write rules
3. Never use `allow read, write: if true;` in production

## Troubleshooting

### "No Firebase App '\[DEFAULT]' has been created"

**Solution**: Ensure config files are in the correct location and rebuild:

```bash theme={null}
bun run clear
bun run prebuild
```

### Analytics Events Not Appearing

**Possible causes**:

* Debug mode not enabled
* Events take time to appear (up to 24 hours in production)
* Invalid event names or parameters

**Solution**: Enable DebugView and check event format

### Authentication Fails

**Possible causes**:

* Sign-in method not enabled in Firebase Console
* Bundle ID / package name mismatch
* Environment variables not set

**Solution**: Verify configuration and check Firebase Console logs

### Crashlytics Not Reporting

**Possible causes**:

* Crashlytics not enabled in Firebase Console
* App not properly configured
* Debug builds don't always report crashes

**Solution**: Test with a release build and verify Crashlytics is enabled

## Official Documentation

* [Firebase Console](https://console.firebase.google.com/)
* [Firebase iOS Setup](https://firebase.google.com/docs/ios/setup)
* [Firebase Android Setup](https://firebase.google.com/docs/android/setup)
* [Firebase Analytics](https://firebase.google.com/docs/analytics)
* [Firebase Crashlytics](https://firebase.google.com/docs/crashlytics)
* [Firebase Authentication](https://firebase.google.com/docs/auth)
* [React Native Firebase](https://rnfirebase.io/)

## Next Steps

* [Configure Environment Variables](/configuration/environment-variables)
* [Configure Adapters](/configuration/adapters)
* [Learn about Analytics Package](/packages/analytics)