Skip to main content

Aghanim-Google Analytics for Firebase Integration

This guide explains how to integrate Aghanim with Google Analytics for Firebase to track purchase events and user behavior. By connecting Aghanim with Google Analytics for Firebase, you can monitor player-generated purchase events from the game hub, ensuring comprehensive tracking of user transactions across your game environment.

info

Aghanim currently sends purchase events to Google Analytics for Firebase only when a player successfully completes a payment on the game hub.

Requirements

Step 1: Get your platform identifiers

Aghanim sends events to different identifiers depending on the platform:

  • Web — uses a Measurement ID (format: G-XXXXXXXXXX).
  • iOS/Android — uses a Firebase App ID (format: 1:NNNNNNNNNNNN:ios:hexhex or 1:NNNNNNNNNNNN:android:hexhex).

Web: Measurement ID

  1. Log in to your Google Analytics dashboard.
  2. Navigate to Admin → Data Streams → select your web data stream.
  3. In the Data stream details, find your Measurement ID and copy it.

iOS/Android: Firebase App ID

  1. Open the Firebase console and select your project.
  2. Go to Project settings → General → Your apps.
  3. Find your iOS or Android app and copy the App ID.

For more details, see the Firebase config file/object reference.

Step 2: Create API Secrets

To enable server-to-server event tracking, you need to create API secrets for the Measurement Protocol. You can create separate API secrets for different platforms (Web, iOS, Android) or reuse the Web API Secret for iOS and Android.

  1. In the Google Analytics dashboard, navigate to Admin → Data Streams and select the data stream for the platform you're configuring (Web, iOS, or Android).
  2. In the Data stream details, scroll down to Measurement Protocol API secrets and click Create.
  3. Provide a nickname for the API secret (e.g., "Aghanim Integration - Web" or "Aghanim Integration - iOS") and click Create.
  4. Copy the generated API Secret value - this is a unique string that authenticates your server-to-server requests.
  5. If you want to use different API secrets for different platforms, repeat steps 2-4 for each platform.

For more details, see the Google Analytics Measurement Protocol documentation.

Step 3: Configure the plugin in Aghanim Dashboard

  1. Go to Aghanim Dashboard → Aghanim Connect → Google Analytics for Firebase and install the plugin.
  2. In the plugin settings, provide credentials for the platforms you support:
    • Web: Measurement ID and API Secret
    • iOS: Firebase App ID and API Secret (iOS-specific)
    • Android: Firebase App ID and API Secret (Android-specific)
  3. Choose the Purchase event name — the GA4 event Aghanim sends on each purchase:
    • purchase (default) — the standard GA4 ecommerce event.
    • in_app_purchase — the event name the Firebase SDK reports for mobile in-app purchases. Choose it when your mobile app already tracks purchases through the Firebase SDK and you want game hub purchases to land in the same reports and Google Ads optimization.

At least one platform must be fully configured. With the default purchase event, each purchase is routed strictly by the order's platform — an iOS purchase uses the iOS credentials or is skipped if iOS isn't configured, and the same applies to Android and Web (no fallback between platforms). The only exception is the API Secret: if you don't set an iOS- or Android-specific API Secret, the Web API Secret is reused for that platform. The in_app_purchase event uses its own routing with fallbacks, described in How it works.

Step 4: Add Google Analytics for Firebase attributes to player.verify webhook response

To track purchases from iOS or Android, include the Firebase-specific attribute in the player.verify webhook response:

KeyTypeDescriptionRequired?
attributes.ga4firebase_app_instance_idstringThe Firebase app_instance_id obtained from the device-side Firebase SDK (Analytics.appInstanceID() on iOS, FirebaseAnalytics.getAppInstanceId() on Android). Required for iOS/Android purchases; web purchases use the GA4 _ga cookie captured automatically by the game hub.Yes (iOS/Android)
attributes.ga4_user_idstringYour cross-device user ID, sent to GA4 as user_id. Defaults to player_id when not set. Max 256 chars.No

Example webhook response:

{
  "player_id": "r2d2-c3po",
  "name": "R2-D2",
  "attributes": {
    "ga4firebase_app_instance_id": "1234567890abcdef1234567890abcdef",
    "ga4_user_id": "u_8f3a1c2b"
  }
}

Alternatively, you can set these attributes at any time via the update_player S2S endpoint — useful when the app obtains the Firebase instance ID after the player.verify exchange (e.g. on a later launch or after the user reinstalls the app):

{
  "attributes": {
    "ga4firebase_app_instance_id": "1234567890abcdef1234567890abcdef",
    "ga4_user_id": "u_8f3a1c2b"
  }
}

If ga4firebase_app_instance_id is missing on an iOS/Android purchase, that event is skipped (the rest of the order flow is unaffected).

How it works

When a player completes a purchase on the game hub, Aghanim sends an event to Google Analytics for Firebase named according to the Purchase event name setting. The user identifier depends on the stream the event goes to:

  • Web stream — sends client_id (the ga4_client_id attribute the game hub captures from the GA4 _ga cookie).
  • iOS/Android App streams — sends app_instance_id (the ga4firebase_app_instance_id attribute supplied by the game).

Both event names share the same base payload:

  • user_id: ga4_user_id if set, otherwise player_id
  • timestamp_micros: purchase timestamp in microseconds (paid_at, or created_at if the order isn't yet paid)
  • currency and value: order currency (e.g. USD) and purchase amount

purchase event

Routed strictly by the order's platform, as described in Step 3. On top of the base payload it carries:

  • transaction_id: unique order identifier
  • items: list of purchased items with their IDs and names

in_app_purchase event

in_app_purchase is an App stream event, so Aghanim prefers the iOS/Android credentials and falls back step by step:

  1. The App stream matching the order's platform (iOS or Android).
  2. The App stream matching the player's platform — the platform reported in the player's attributes, or the platform of the marketplace the player came from.
  3. The Web stream — in this case the event is sent under the regular purchase name, since in_app_purchase is not meaningful for web data streams.

A step is skipped when its credentials aren't configured or the player has no ga4firebase_app_instance_id. If no step succeeds, the event is skipped entirely (the rest of the order flow is unaffected).

This integration ensures that all purchase events from your game hub are automatically tracked in Google Analytics for Firebase, providing comprehensive insights into player spending behavior and purchase patterns.

Need help?
Contact our integration team at integration@aghanim.com

On this page