Firebase

The Firebase integration automatically sends Superwall subscription and payment events to Firebase Analytics (Google Analytics 4) using the Measurement Protocol. Track subscription lifecycle events, analyze revenue metrics, and leverage Firebase's powerful analytics capabilities with automatic event mapping and ecommerce tracking.

Features

• Standard Ecommerce Events: Uses Firebase's standard purchase and refund events for revenue tracking
• Measurement Protocol: Direct server-side integration via Google Analytics Measurement Protocol
• Revenue Tracking: Automatic revenue attribution with ecommerce parameters
• Sandbox Isolation: Separate tracking for production and sandbox events
• Custom Event Mapping: Non-revenue events mapped to custom Firebase events
• Cross-Platform User Tracking: Optional user_id for cross-device analysis
• Debug Validation: Built-in validation via Firebase's debug endpoint
• Platform Attribution: Tracks which store (App Store, Play Store, Stripe) generated revenue

Configuration

Firebase requires separate credentials for iOS and Android apps since each platform has its own data stream in Firebase Analytics. You can configure one or both platforms depending on your app.

iOS Settings

Android Settings

Common Settings

Note: At least one platform (iOS or Android) must have both firebase_app_id and api_secret configured. Events from platforms without credentials will be skipped.

Example Configuration (Both Platforms)

{
  "ios_firebase_app_id": "1:123456789012:ios:abcdef1234567890",
  "ios_api_secret": "your_ios_api_secret",
  "sandbox_ios_firebase_app_id": "1:123456789012:ios:sandbox1234567890",
  "sandbox_ios_api_secret": "your_ios_sandbox_api_secret",
  "android_firebase_app_id": "1:123456789012:android:fedcba0987654321",
  "android_api_secret": "your_android_api_secret",
  "sandbox_android_firebase_app_id": "1:123456789012:android:sandbox0987654321",
  "sandbox_android_api_secret": "your_android_sandbox_api_secret",
  "sales_reporting": "Revenue",
  "anonymous_user_behavior": "send"
}

Example Configuration (iOS Only)

{
  "ios_firebase_app_id": "1:123456789012:ios:abcdef1234567890",
  "ios_api_secret": "your_ios_api_secret",
  "sales_reporting": "Revenue"
}

App Instance ID Requirement

Critical: The Firebase integration requires firebaseAppInstanceId to be set in the user's userAttributes from your client app. This is the unique installation identifier from the Firebase Analytics SDK.

How to Set It Up

1. In your app, retrieve the Firebase App Instance ID:

iOS (Swift):

import FirebaseAnalytics

Analytics.appInstanceID { appInstanceId, error in
    if let appInstanceId = appInstanceId {
        Superwall.shared.setUserAttributes([
            "firebaseAppInstanceId": appInstanceId
        ])
    }
}

Android (Kotlin):

import com.google.firebase.analytics.FirebaseAnalytics

FirebaseAnalytics.getInstance(context).appInstanceId.addOnSuccessListener { appInstanceId ->
    Superwall.instance.setUserAttributes(mapOf(
        "firebaseAppInstanceId" to appInstanceId
    ))
}

What Happens Without It

If firebaseAppInstanceId is not found in userAttributes:

• The event is skipped (not sent to Firebase)

Revenue Events (Standard Ecommerce)

Events with non-zero amounts use Firebase's standard ecommerce events for proper revenue tracking:

Non-Revenue Events (Custom Events)

Events without revenue are mapped to custom Firebase events (lowercase, underscores):

Event Parameters

Required Parameters (All Events)

Every Firebase event includes these parameters:

Ecommerce Parameters (Revenue Events)

Purchase and refund events include additional ecommerce fields:

Items Array Structure:

{
  "items": [
    {
      "item_id": "com.example.premium_monthly",
      "item_name": "com.example.premium_monthly",
      "price": 9.99,
      "quantity": 1
    }
  ]
}

Non-Revenue Event Parameters

Non-revenue events include:

Revenue Tracking

Automatic Revenue Attribution

Revenue is tracked using Firebase's standard ecommerce events:

• Positive revenue: purchase event with positive value
• Negative revenue: refund event with positive value (Firebase expects absolute values)
• Zero revenue: Custom event (no ecommerce parameters)

Revenue Reporting Options

The sales_reporting setting determines which value is used:

Revenue Examples

Initial Purchase ($9.99):

{
  "name": "purchase",
  "params": {
    "currency": "USD",
    "value": 9.99,
    "transaction_id": "1000000123456789",
    "items": [
      {
        "item_id": "com.example.premium",
        "item_name": "com.example.premium",
        "price": 9.99,
        "quantity": 1
      }
    ],
    "session_id": "1699876543000",
    "engagement_time_msec": 100,
    "store": "APP_STORE",
    "environment": "Production"
  }
}

Refund (-$9.99):

{
  "name": "refund",
  "params": {
    "currency": "USD",
    "value": 9.99,
    "transaction_id": "1000000123456789",
    "items": [
      {
        "item_id": "com.example.premium",
        "item_name": "com.example.premium",
        "price": 9.99,
        "quantity": 1
      }
    ],
    "session_id": "1699876543000",
    "engagement_time_msec": 100,
    "store": "APP_STORE",
    "environment": "Production"
  }
}

Platform Tracking & Automatic Credential Selection

The integration automatically selects the correct Firebase credentials based on the store field in each event:

Note: If credentials are not configured for a platform, events from that platform will be skipped. For example, if you only configure iOS credentials, Play Store events will be skipped.

With Platform Sandbox Credentials

If sandbox credentials are configured for a platform:

• Production events → Production Firebase project (using production credentials)
• Sandbox events → Sandbox Firebase project (using sandbox credentials)

Example for iOS:

• iOS production event → Uses ios_firebase_app_id + ios_api_secret
• iOS sandbox event → Uses sandbox_ios_firebase_app_id + sandbox_ios_api_secret

Without Platform Sandbox Credentials

If sandbox credentials are NOT provided for a platform:

• Production events → Production Firebase project
• Sandbox events → Skipped (not sent)

This behavior is per-platform, so:

• You can have iOS sandbox credentials but skip Android sandbox events
• You can configure sandbox for Android but not iOS
• Each platform is independent

This prevents test data from polluting production analytics.

Testing the Integration

1. Validate Credentials

The integration validates settings using Firebase's debug endpoint:

• Sends a test event to Firebase
• Validates event format and structure
• Important: The debug step does NOT validate api_secret or firebase_app_id

2. Verify in Firebase Console

After sending events, verify in Firebase:

1. DebugView: Firebase Console → Analytics → DebugView (for real-time debugging)
2. Events: Firebase Console → Analytics → Events (may take up to 24 hours)
3. Revenue: Firebase Console → Analytics → Revenue (for purchase/refund events)

Best Practices

1. Set App Instance ID Early: Call setUserAttributes with firebaseAppInstanceId as soon as the app launches to ensure all subscription events are tracked.

2. Separate Environments: Use separate Firebase projects (or at minimum, separate measurement streams) for sandbox and production to keep analytics clean.

3. Revenue Model Consistency: Choose gross (Revenue) vs net (Proceeds) consistently and document your choice for reporting alignment.

4. Enable DebugView: During testing, enable Firebase DebugView on your test device to see events in real-time.

5. Use User ID: Set originalAppUserId in Superwall to enable cross-device user tracking in Firebase Analytics.

Common Use Cases

Revenue Analytics

Event: purchase
Breakdown by: store, country_code, product_id (via items)
Metric: Sum of value

Conversion Funnel

1. trial_start
2. purchase (trial conversion)
Conversion Rate: Step 2 / Step 1

Churn Analysis

Events: subscription_cancellation, subscription_expiration
Segment by: period_type, store

LTV Calculation

Event: purchase
Group by: user_id
Calculate: Sum of value per user

Troubleshooting

Events Not Appearing in Firebase

1. Check App Instance ID: Ensure firebaseAppInstanceId is set in userAttributes
2. Verify Platform Credentials: Confirm the correct platform credentials are configured:
   • iOS events (App Store) require ios_firebase_app_id + ios_api_secret
   • Android events (Play Store) require android_firebase_app_id + android_api_secret
3. Check Environment: Sandbox events require sandbox credentials for that platform
4. Wait for Processing: Events may take up to 24 hours to appear in standard reports (use DebugView for real-time)

Events Skipped Due to Missing Platform Credentials

Problem: Events are being skipped with warning "No [platform] credentials configured"

Solutions:

1. iOS events skipped: Add ios_firebase_app_id and ios_api_secret
2. Android events skipped: Add android_firebase_app_id and android_api_secret
3. Sandbox events skipped: Add sandbox credentials for the specific platform (e.g., sandbox_ios_firebase_app_id + sandbox_ios_api_secret)

Single-Platform Apps: If your app is iOS-only or Android-only, you only need to configure credentials for that platform. Events from unconfigured platforms will be skipped (this is expected behavior).

Missing firebaseAppInstanceId

Problem: Events are being skipped with warning about missing firebaseAppInstanceId

Solutions:

1. Ensure your app calls FirebaseAnalytics.getAppInstanceId() and passes it to Superwall
2. Verify setUserAttributes is called before any purchases occur
3. Check that the attribute key is exactly firebaseAppInstanceId (case-sensitive)

Revenue Not Tracking

1. Check Event Type: Only purchase and refund events track revenue
2. Check Amount: Zero amounts don't create revenue events
3. Check Currency: Ensure currencyCode is present in the webhook data
4. Check Firebase Reports: Revenue appears in Analytics → Revenue (not Events)

Debug Validation Errors

Problem: Credential validation returns errors

Common Causes:

• Invalid event parameter names (must be alphanumeric with underscores)
• Missing required parameters (session_id, engagement_time_msec)
• Invalid app_instance_id format

Note: The debug endpoint validates event format but cannot validate whether your api_secret or firebase_app_id are correct. You must verify events appear in Firebase Console.

Duplicate Events

Firebase handles deduplication via transaction_id:

• Same transaction_id within 72 hours is deduplicated
• Ensure unique transaction IDs for each event

Rate Limits

Google Analytics Measurement Protocol limits:

The integration sends one event per request, well within all limits.

Data Privacy

• App Instance ID: Pseudonymous device identifier
• User ID: Optional, only sent if originalAppUserId is set
• Data Retention: Follows your Firebase project settings
• Deletion: Handle via Google Analytics User Deletion API
• GDPR: Firebase Analytics provides data processing agreements and privacy controls
• PII: Avoid sending PII in custom parameters