Set up Firebase as an analytics platform

This article guides you on setting up Firebase as an analytics platform, allowing your game to report telemetry data directly to Firebase.

Firebase Setup Required

Before building your project, ensure that the steps detailed in this article to set up Firebase has been completed, to avoid app crashes on launch.

info

Firebase must run on devices with Android 4.0 or later, with Google Play Services 11.0.2 or later installed.

Prerequisites

note

Firebase supports multi-store packages through adding multiple apps to the same project. Create additional Firebase apps on the Firebase Console and complete the configurations for additional Firebase apps by repeating the following steps.

1. Register a Firebase project

Go to the Firebase Console and follow the instructions to register a Firebase project.

2. Add an app

note

Firebase supports multi-store packages through adding multiple apps to the same project. Create additional Firebase apps on the Firebase Console and complete the configurations by repeating the following steps.

1. In the Project Overview page of the Firebase Console, add the Firebase App for the corresponding platform.

   

2. Follow the instructions to enter the relevant information.

3. Add Firebase to your Android App.

   

   1. Enter relevant information, and then click REGISTER APP.
      If you are unsure about the values for certain fields, you can add them later.
   2. Download the google-services.json file for reference. You can download it again from the Firebase Console.
   3. Skip other steps.

4. Add Firebase to your iOS App.

   

   1. Enter relevant information, and then click REGISTER APP.
      If you are unsure about the values for certain fields, you can add them later.
   2. Download the google-services.jsonfile for reference. You can download it again from the Firebase Console.
   3. Configure the APNs certificate for the push function.

3. Upload iOS APNs certificate

1. In the Settings page, click CLOUD MESSAGING to find the iOS project.

   

2. Add the development APNs certificate and production APNs certificate respectively.

   

For more information, see Configuring APNs with FCM.

4. Project configurations

In the Project settings page, you can continue to set up your project, download the google-services.json file and the GoogleService-Info.plist file, or configure the Android certificate fingerprint.

5. Integrate the Player Network SDK.

Step 1: Set up permissions and configurations

Android

User permissions

caution

Because the Firebase SDK is only compatible with minSdkVersion >= 19 or later, it may have problems when running on Android 4.2 or earlier. Set minSdkVersion >= 19 for your game.

Firebase requires permission to access the internet.

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Configurations

Configure the Android client key in the INTLConfig.ini file.

[Google]
GOOGLE_CLIENT_KEY_ANDROID = {YOUR_CLIENT_KEY_ANDROID}

• Replace {YOUR_CLIENT_KEY_ANDROID} with Web client Key required by Player Network SDK. It is the client ID for web applications in the Credentials section during API OAuth configuration, also known as Server Client ID during OAuth 2.5 API configuration.

google-services.json

caution

The build will fail without the google-services.json file.

The gradle build method can directly process the google-services.json file, and convert the content to a corresponding app/build/generated/res/google-services/{build_type}/values/values.xml configuration file.

Unity

For more information on adding and placing the google-services.json file in the Assets/Plugins/Android/ directory, see The Google Services Gradle Plugin.

Unreal Engine

For more information on adding and placing the google-services.json file in the Plugins/INTLSDK/Source/INTLFirebase/Libs/Android directory, see The Google Services Gradle Plugin.

iOS

Configurations

Firebase Plist

caution

The build will fail without the GoogleService-info.plist file.

Place the GoogleService-info.plist configuration file under the Assets/Plugins/iOS/INTLSDK/INTLFirebase/ThirdSDK/ directory.

[Optional] Export Xcode with Unity

Before exporting the Xcode project, the .projmods file has to be configured first.

Player Network SDK has included the below configurations in the INTLFirebaseKit.projmods file, ensure that the information is correct.

{
    "group": "INTL",
    "libs": [],
    "frameworks": [],
    "files": [
        "Plugins/iOS/INTLSDK/INTLFirebase/GoogleService-Info.plist"
    ],
    "folders": [],
    "excludes": [],
    "headerpaths":[],
    "build_settings": {},
    "system_capabilities": {"com.apple.Push":"TRUE"},
    "Info.plist":{},
}

For more information regarding Xcode project exporting, see Player Network SDK XUPorter solution.

[Optional] Private Set Membership

Private Set Membership (PSM) is a cryptographic technique to verify for existing user data in a large dataset held by another party, without revealing the data itself or learning anything else about the dataset, thereby increasing the observable conversions from iOS app campaigns.

Since Player Network SDK V1.19.00, Google PSM functionalities has been added for the iOS client, to increase the accuracy of player signals and improve ad buying effectiveness.

The PSM function is disabled by default. To enable the function, permission to obtain a player's email from the corresponding identity provider is required. The following identity providers are compatible with PSM on Player Network SDK:

• LI PASS
• Apple
• Facebook
• Google
• Twitter

After permissions have been obtained, add the following configuration under the Firebase node in INTLConfig.ini:

ANALYTICS_FIREBASE_REPORT_EMAIL = 1

With PSM being enabled, a player's email will be sent to Google's server through the API provided by Firebase when the player logs in with a new account, and the conversion rate of advertisements will be calculated by Google Analytics. For acceptance of the PSM function, see Acceptance use case 4.

For more information regarding PSM, see Tutorial: Measure Google Ads conversions from your iOS app campaigns.

Step 2: Get instanceId asynchronously

note

Since Firebase's instanceID fetch is asynchronous, calling getInstanceID may return null. It is recommended to get instanceId asynchronously.

Unity

INTLAPI.ExtendInvoke("Firebase", "getInstanceIDAsync", "");
INTLAPI.AddExtendResultObserver(OnExtendEvent);
void OnExtendEvent(INTLExtendResult ret)
{
   //Extend callback
}

Unreal Engine

INTLWrapper::Instance()->ExtendInvoke("Firebase", "getInstanceIDAsync", "").c_str();

//Need to implement in subclasses
AnalyticsWindow.h
virtual void UAnalyticsWindow::OnExtendResult_Implementation(FINTLExtendResult ret) {
   //Extend callback
}

Step 3: Configure event reporting

caution

Firebase will collect the Android IDs of player devices. To disable the collection of Android IDs, see Disable SSAID collection.

Events are important events in your game that you wish to measure, each game can report up to 500 different types of events and can associate up to 25 unique parameters with each event type. You may choose to specify custom event types to be associated with your game.

Each event type is identified by a unique name. Event names can be up to 40 characters long, can only contain alphanumeric characters and underscores ("_"), and must begin with an alphabet character. The "firebase_", "google_" and "ga_" prefixes are reserved and should not be used.

See the FirebaseAnalytics.Event documentation for more information.

Manually logged events

To register custom key-value parameters for the reported events, click Manage Custom Definitions from the Firebase Console.

After custom key-value parameters have been registered successfully, they are displayed as follows:

Funnel events

note

Supported since Player Network SDK V1.20.

Add the Firebase channel to the ANALYTICS_REPORT_FUNNEL_CHANNEL configuration in INTLConfig.ini, and Player Network SDK will synchronize the funnel events to the Firebase channel.

[ANALYTICS]
ANALYTICS_REPORT_FUNNEL_CHANNEL = Firebase

See View reported events in the console to view the reported events.

Crash reporting

caution

No longer supported for Player Network SDK V1.17 and later.

Step 4: Initialize Analytics

Unity

Initialize the Analytics module, then call ReportEvent to start Firebase data reporting.

Unreal Engine

Initialize the Analytics module, then call ReportEvent to start Firebase data reporting.

Data reporting acceptance

References

1. Firebase login page
2. Getting Started (Android) / Getting Started (iOS)
3. Test Mode

Data dimensions

Firebase events:

• Auto collected events: first_open, session_start, screen_view, and more.
• Recommended events: level_start and level_end
  Add these events to a website or mobile app to help measure other functions and behaviors and generate more useful reports. Because these events require additional context to be meaningful, they are not automatically sent by global site labels.
• Custom events: ReportEvent
  Use the API to set events with custom eventname

For more information, see Events and Properties.

View reported events in the console

caution

Events are not reported in realtime, with a latency of 1 hour or more.

Go to Firebase Console to view the reported events.

View reported events in debug mode

Generally, the events recorded by Firebase are collected for batch processing and uploading almost every hour. This reduces the power consumption and data usage for the device. To verify the event reporting with the shortest delay, enable debug mode on the development device.

For more information on enabling debug mode, see Firebase Debugging Events.

iOS

note

The latency in debug mode is about 20s.

To view event reporting from the Firebase console:

1. From the Firebase console, select DebugView.
2. Select the device model to view reported events.
   

To view event reporting from the Xcode debug console:

1. In Xcode, click Product > Scheme > Edit scheme.
2. In the left pane, select Run.
3. Select the Arguments tag.
4. In the Arguments Passed On Launch section, add -FIRAnalyticsDebugEnabled.

Android

note

The latency in debug mode is about 5s.

1. Execute the command bash adb shell setprop debug.firebase.analytics.app {package_name}.
2. From the Firebase console, select the device model on the DebugView page.
   

note

The debug mode remains enabled until it is explicitly disabled by executing the following command:
bash adb shell setprop debug.firebase.analytics.app .none.

Acceptance use case 1

• Sub-function module: Reporting

• Feature: Event Reporting

• Test points: Event information successfully reported by Firebase

• Prerequisites: Initialize Analytics module

• Procedure/Input

  1. Request ReportRevenue
  2. eventName = Report_Event, paramsDic-key1=k1, paramsDic-value1=v1, paramsDic-key2=k2, paramsDic-value2=v2, spChannels=Firebase
  3. Install/Uninstall SDK and launch game
  4. Go to the console and click Events to view the reported first_open events

• Expected output: Information reported successfully.
  In the console: Use Firebase to query reported events and query set parameters.

  1. Open the app and view session_start events: Reported qty+1
     Check: eventName = Report_Event, paramsDic-key1=k1, paramsDic-value1=v1, paramsDic-key2=k2, paramsDic-value2=v2, spChannels = Firebase
  2. Install/Uninstall first_open event reported qty+1, view install/uninstall and check first_open events: Reported qty+1
     Check: sDic-value2=v2 spChannels = Firebase

Acceptance use case 2

• Sub-function module: ReportRevenue
• Feature: Firebase payment event reporting
• Test points: Query report after requesting ReportRevenue (Firebase)
• Prerequisite: Network connection is normal
  • Procedure/Input
  1. Request ReportRevenue
  2. eventName = (customizable), spChannels = Firebase, Currency = USD, Revenue = 100
  3. Firebase query report event
  4. DD Platform query AnalyticsReportRevenue event
• Expected output: Information reported successfully.
  1. Firebase related event statistics +1, click on the event details display to display USD100 related values.
  2. DD Platform successfully queries the event reporting with methodName as AnalyticsReportRevenue and method_id=715.

Acceptance use case 3

• Sub-function module: ReportRevenue
• Feature: Firebase payment event reporting
• Test points: Query report after requesting ReportRevenue in disconnected state (Firebase)
• Prerequisite: Disconnected network status
• Procedure/Input
  1. Request ReportRevenue
  2. eventName = (customizable), spChannels = Firebase, Currency = USD, Revenue = 1000
  3. Reconnect to the network
  4. Firebase query report event
  5. DD Platform query AnalyticsReportRevenue event
• Expected output: Information reported successfully.
  1. Firebase related event statistics +1, click the event details display to display the USD1000 related values.
  2. The DD Platform successfully queries the event reporting with methodName as AnalyticsReportRevenue and method_id=715.

Acceptance use case 4

• Sub-function module: Reporting
• Feature: PSM reporting for iOS
• Test points: Initialize PSM
• Prerequisite: PSM function enabled
• Procedure/Input
  1. Open the iOS project of the game with Xcode, and enable debug mode.
  2. Uninstall the game app from the test device.
  3. Reinstall the game app using Xcode.
  4. Log in to the game with a channel that has email permissions enabled.
  5. Refer to Firebase: Initiate on-device conversion measurement using Google Analytics to verify that PSM is initialized.
• Expected output: Either one of the following messages can be found from the log output of Xcode.
  • On-device conversion measurement found a match
  • On-device conversion measurement did not find a match.

Repeat steps 2 to 5 for the other login channels that use PSM for email reporting.

Error codes

For more information, see Firebase Docs.