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

# Adapter Configuration

> Configure service adapters for authentication, subscriptions, and analytics

# Adapter Configuration

Configure service adapters to switch between mock implementations and production services.

## Understanding Adapters

The starter uses an adapter pattern for key services:

* **Authentication** - Mock or Firebase
* **Subscriptions** - Mock or RevenueCat
* **Analytics** - Mock or Firebase

This allows you to:

* Develop without production services
* Switch providers easily
* Test with mock data
* Use different adapters per environment

## Configuration Files

Adapters are configured in two places:

1. **`amisi.config.json`** - Adapter selection
2. **`packages/config/src/flags.ts`** - Feature flags to enable/disable services

## Authentication Adapter

### Available Adapters

* **`mock`** - Simulated authentication (development)
* **`firebase`** - Firebase Authentication (production)

### Configure in amisi.config.json

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

### Mock Adapter

The mock adapter provides simulated authentication:

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

**Features:**

* No external dependencies
* Instant sign-in/sign-up
* Simulated user sessions
* Perfect for development

**Limitations:**

* No real authentication
* Data not persisted
* No password validation

### Firebase Adapter

The Firebase adapter uses Firebase Authentication:

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

**Requirements:**

* Firebase project configured
* `GoogleService-Info.plist` (iOS)
* `google-services.json` (Android)
* Environment variables set

**Features:**

* Email/password authentication
* Social sign-in (Google, Apple, etc.)
* Password reset
* Email verification
* Multi-factor authentication

**Setup:**

1. Follow [Firebase Setup](/configuration/firebase-setup) guide
2. Set environment variables
3. Enable authentication methods in Firebase Console
4. Rebuild native projects

## Subscriptions Adapter

### Available Adapters

* **`mock`** - Simulated subscriptions (development)
* **`revenuecat`** - RevenueCat (production)

### Configure in amisi.config.json

```json theme={null}
{
  "subscriptions": {
    "adapter": "revenuecat"
  }
}
```

### Mock Adapter

The mock adapter provides simulated subscriptions:

```json theme={null}
{
  "subscriptions": {
    "adapter": "mock"
  }
}
```

**Features:**

* No external dependencies
* Simulated products
* Instant purchases
* Simulated subscription status

**Limitations:**

* No real payments
* No App Store/Play Store integration
* Data not persisted

### RevenueCat Adapter

The RevenueCat adapter integrates with RevenueCat for subscription management:

```json theme={null}
{
  "subscriptions": {
    "adapter": "revenuecat"
  }
}
```

**Requirements:**

* RevenueCat account
* App configured in RevenueCat dashboard
* API keys set in environment variables
* Products configured in App Store Connect / Google Play Console

**Features:**

* Real subscription purchases
* Cross-platform subscription management
* Receipt validation
* Subscription analytics
* Webhooks for server-side events

**Setup:**

1. Create [RevenueCat account](https://www.revenuecat.com/)
2. Add your app to RevenueCat dashboard
3. Configure products in App Store Connect / Google Play Console
4. Link products in RevenueCat
5. Set environment variables:
   ```bash theme={null}
   EXPO_PUBLIC_REVENUECAT_API_KEY=your-key
   ```
6. Rebuild native projects

**Documentation:**

* [RevenueCat Getting Started](https://www.revenuecat.com/docs/getting-started)
* [Subscriptions Package](/packages/subscriptions)

## Analytics Adapter

### Available Adapters

* **`mock`** - No-op analytics (development)
* **`firebase`** - Firebase Analytics + Crashlytics (production)

### Configure with Feature Flags

Analytics is controlled by feature flags in `packages/config/src/flags.ts`:

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

const developmentFlags: FeatureFlags = {
  enableAnalytics: false, // Use mock adapter
  enableCrashReporting: false,
  // ... other flags
};
```

### Mock Adapter

When analytics is disabled, the mock adapter is used:

```typescript theme={null}
const developmentFlags: FeatureFlags = {
  enableAnalytics: false,
  enableCrashReporting: false,
};
```

**Features:**

* No external dependencies
* Silent (no-op)
* No network requests

**Use when:**

* Developing locally
* Testing without analytics
* Running in Expo Go

### Firebase Adapter

When analytics is enabled, the Firebase adapter is used:

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

**Requirements:**

* Firebase project configured
* `GoogleService-Info.plist` (iOS)
* `google-services.json` (Android)
* Native build (not Expo Go)

**Features:**

* Firebase Analytics (GA4)
* Firebase Crashlytics
* Automatic screen tracking
* Custom event tracking
* User properties
* Crash reporting

**Setup:**

1. Follow [Firebase Setup](/configuration/firebase-setup) guide
2. Enable feature flags
3. Rebuild native projects

**Documentation:**

* [Analytics Package](/packages/analytics)

## Environment-Specific Configuration

Use different adapters for different environments:

### Development

```json theme={null}
{
  "auth": {
    "adapter": "mock"
  },
  "subscriptions": {
    "adapter": "mock"
  }
}
```

```typescript theme={null}
const developmentFlags: FeatureFlags = {
  enableAnalytics: false,
  enableCrashReporting: false,
};
```

### Preview

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

```typescript theme={null}
const previewFlags: FeatureFlags = {
  enableAnalytics: true,
  enableCrashReporting: true,
};
```

### Production

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

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

## Testing Adapter Changes

After changing adapters:

1. **Update configuration files**:
   * `amisi.config.json`
   * `packages/config/src/flags.ts`

2. **Set environment variables** (if using production adapters):
   * Firebase variables
   * RevenueCat variables

3. **Rebuild native projects** (if using Firebase or RevenueCat):

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

4. **Restart development server**:

   ```bash theme={null}
   bun run start:clear
   ```

5. **Test functionality**:
   * Sign in/sign up (auth)
   * View products (subscriptions)
   * Navigate screens (analytics)

## Adapter Initialization

Adapters are initialized at app startup in `apps/mobile/app/_layout.tsx`:

### Authentication

```typescript theme={null}
import { initializeAuth } from '@amisi/auth';

await initializeAuth({
  adapter: config.auth.adapter,
  options: {},
});
```

### Subscriptions

```typescript theme={null}
import { initializeSubscriptions } from '@amisi/subscriptions';

await initializeSubscriptions({
  adapter: config.subscriptions.adapter,
  options: {
    apiKey: env.EXPO_PUBLIC_REVENUECAT_API_KEY,
  },
});
```

### Analytics

```typescript theme={null}
import { initializeAnalytics } from '@amisi/analytics';

await initializeAnalytics({
  adapter: flags.enableAnalytics ? 'firebase' : 'mock',
  options: {
    enableAnalytics: flags.enableAnalytics,
    enableCrashReporting: flags.enableCrashReporting,
  },
});
```

## Creating Custom Adapters

You can create custom adapters for other services:

### 1. Implement the Adapter Interface

```typescript theme={null}
import { AuthAdapter } from '@amisi/auth';

export function createCustomAuthAdapter(): AuthAdapter {
  return {
    name: 'custom',

    async initialize(config) {
      // Initialize your service
    },

    async signIn(params) {
      // Implement sign in
      return null;
    },

    async signUp(params) {
      // Implement sign up
      return null;
    },

    async signOut() {
      // Implement sign out
    },

    async getSession() {
      // Get current session
      return null;
    },

    async cleanup() {
      // Cleanup resources
    },
  };
}
```

### 2. Register the Adapter

```typescript theme={null}
import { registerAuthAdapter } from '@amisi/auth';

registerAuthAdapter(createCustomAuthAdapter());
```

### 3. Use the Adapter

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

## Common Issues

### Adapter Not Found

**Error**: `Adapter 'firebase' not found`

**Solution**: Ensure the adapter is registered and dependencies are installed.

### Initialization Failed

**Error**: `Failed to initialize adapter`

**Solution**: Check that:

* Environment variables are set
* Config files are in place (Firebase)
* Native projects are rebuilt

### Mock Adapter in Production

**Warning**: Never use mock adapters in production builds.

**Solution**: Verify `amisi.config.json` and feature flags for production environment.

## Best Practices

1. **Use mock adapters for development** - Faster iteration, no external dependencies
2. **Test with production adapters before release** - Catch integration issues early
3. **Use environment-specific configuration** - Different adapters per environment
4. **Keep secrets secure** - Use EAS Secrets for production API keys
5. **Document adapter requirements** - Make it clear what's needed for each adapter

## Next Steps

* [Learn about Auth Package](/packages/auth)
* [Learn about Subscriptions Package](/packages/subscriptions)
* [Learn about Analytics Package](/packages/analytics)
* [Configure Environment Variables](/configuration/environment-variables)