Skip to main content

Getting Started with GameAnalytics Unity SDK

This guide explains how to integrate the GameAnalytics SDK into your Unity project (Unity 2019.4+).

tip

Stay updated with the latest changes by checking the GameAnalytics Unity SDK Changelog.

1. Install the SDK​

Choose the install method that suits your workflow: Unity Package Manager or Custom Package.

1.1. Setup using Unity Package Manager (UPM)​

Install External Dependency Manager for Unity:

  1. Download the latest version of External Dependency Manager for Unity (pick .tgz) from here.

  2. Create a new folder next to your project's Packages folder and name it GooglePackages, then place the .tgz files into that folder.

  3. Add the Package in Unity:

  • Open your Unity project.

  • Go to Window > Package Manager.

  • Click the + button (top-left corner) and select Add package from tarball….

    UPM Add Tarball Screenshot

  • Locate and select the downloaded .tgz file.

  • Unity will import the package.

Official install instructions for External Dependency Manager for Unity described here.

Configure manifest.json

  1. Locate the manifest.json File:

    • Navigate to your Unity project folder.
    • Open the Packages/manifest.json file in a text editor.

  2. Edit the dependencies Section: Add the following line:

    "com.gameanalytics.sdk": "[latest_version]"

  3. Edit the scopedRegistries Section: If the scopedRegistries section does not exist, create it. Add the following lines:

    "scopedRegistries": [
      {
        "name": "Game Package Registry by Google",
        "url": "https://unityregistry-pa.googleapis.com/",
        "scopes": [
          "com.google"
        ]
      },
      {
        "name": "package.openupm.com",
        "url": "https://package.openupm.com",
        "scopes": [
          "com.gameanalytics"
        ]
      }
    ]

1.4. Configuration for Android​

If your game uses proguard add these rules to your proguard rules:


  -keep class  com.gameanalytics.sdk { *; }
  -keep class  com.gameanalytics.sdk.** { *; }

  -keep class  com.gameanalytics.sdk.GAPlatform { *; }
  -keep class  com.gameanalytics.sdk.GAPlatform.** { *; }
  -keep class android.net.ConnectivityManager.** { *; }
  -keep class com.google.android.instantapps.InstantApps { *; }
  -keepclassmembers class com.google.android.instantapps.InstantApps{*; }

2. SDK Integration​

2.1. Create Account​

info

If you don't have an account created yet, head over here and register your game on the GameAnalytics website!

After you've set up your organization, studio and game, you will be able to access your game's keys within the game settings section of the web tool.

2.2. Login​

Through the toolbar menu select Window/GameAnalytics/Select Settings. A Settings gameobject will automatically be created if not located.

Unity Select Settings

  • Click the Login button in Settings and enter your credentials.

2.3. Configure Game Keys​

After login, you can select an existing studio/game by selecting your platform and then Add Platform. When selected the game key and the secret key will be automatically fetched and configured. Example:

Configured Game Keys

Optionally, you can manually configure the game and secret keys for your game.

2.4. Create a GameAnalytics GameObject​

To use GameAnalytics you need to add the GameAnalytics GameObject to your starting scene. It is required and used to handle initialization when the game is launched.

Open the initial scene the game will load. Then select: Window > GameAnalytics > Create GameAnalytics object

Unity GameObject

A GameAnalytics object will be placed in the scene you are currently on (remember to save the scene to keep the changes).

caution

Make sure only one GameAnalytics object exists in your entire game. It will not be destroyed upon scene changes.

2.5. Initialize the SDK​

You need to manually initialize the SDK by calling GameAnalytics.Initialize() from your own GameObject (with script execution order coming after GameAnalytics script’s order if your object is in the same scene as the GameAnalytics object as some code is called on Awake event which needs to be called before initializing the sdk).


// Usage Example:
// SDK Key and SDK Secret are set on the Settings object
GameAnalytics.Initialize();

2.6. iOS - Handle App Tracking Transparency(ATT) Consent​

info

Starting with iOS 14.5, apps must ask for user consent (using the App Tracking Transparency framework) before they can access and share some user data, including the device's IDFA, which is helpful for tracking purposes.

The GameAnalytics SDK will track ATT Consent Status on all events.
To track this properly you need to make sure you have shown the ATT Consent dialog before initializing the SDK.

important

It is important to still initialize the SDK even if the user doesn't authorize the game to track the user for advertising purposes.
The GameAnalytics Unity SDK uses IDFV (for iOS) as the user id and it will only add IDFA to events if ATT consent status is authorized.

If you want the SDK to handle the ATT prompt for you, check the following code example:


  using UnityEngine;
  using GameAnalyticsSDK;

  public class MyScript : MonoBehaviour, IGameAnalyticsATTListener
  {
      void Start()
      {
          if(Application.platform == RuntimePlatform.IPhonePlayer)
          {
              GameAnalytics.RequestTrackingAuthorization(this);
          }
          else
          {
              GameAnalytics.Initialize();
          }
      }

      public void GameAnalyticsATTListenerNotDetermined()
      {
          GameAnalytics.Initialize();
      }
      public void GameAnalyticsATTListenerRestricted()
      {
          GameAnalytics.Initialize();
      }
      public void GameAnalyticsATTListenerDenied()
      {
          GameAnalytics.Initialize();
      }
      public void GameAnalyticsATTListenerAuthorized()
      {
          GameAnalytics.Initialize();
      }
  }
info

Remember to add a usage-description to the info.plist file as described here.

2.7. Send the User ID to GameAnalytics​

The SDK will automatically generate a user id and this is perfectly fine for almost all cases.
Sometimes it is useful to supply the User ID manually – for example, if you download raw data for processing and need to match your internal user id (could be a database index on your user table) to the data collected through GameAnalytics.

caution

Note that if you introduce this into a game that is already deployed (using the automatic id) it will start counting existing users as new users and your metrics will be affected. Use this from the start of the app lifetime.

Use the following piece of code to set the custom user id:


GameAnalytics.SetCustomId("myCustomUserId");
caution

Remember when using a custom id you need to set it before initializing GameAnalytics SDK or else it will not be used.

3. Tracking Events​

3.1. When to Log Events​

info

Remember to only send events from main thread as the SDK internally uses some Unity functions which can only be used from main thread.

Unity provides the GameObject methods called awake and start. First all GameObjects get the awake call. When every awake is done then all GameObjects get the start call.
The execution order for each is not fixed.
The GameAnalytics settings GameObject is initialized in the awake method, but other GameObjects could have had their awake call happen before this.
Therefore when submitting events from GameObjects in Unity it is recommended to do this after (or inside) the start method. This will ensure everything is ready.
If an event is submitted before initialization then the log will output something like this.


Warning/GameAnalytics: Could not add design event: Datastore not initialized
caution

No events are actually being generated in the Editor. You need to build and run the game for the platform of your interest.

tip

Read more about Unity execution order here.

3.2. Start Tracking Events​

The GameAnalytics SDK supports 5 different types of events: Business, Resource, Progression, Error and Design.
Learn more about what each event type and how to use them on the Event Tracking page.