Skip to main content

Getting Started with GameAnalytics Unity SDK

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

tip

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

GameAnalytics Documentation Assistants

Need a quick summary or compatibility check?

  • Claude: add our official connector from the Claude library in one click, no configuration needed.
  • ChatGPT: ask in your browser, no setup required.
  • Custom connectors: connect any other AI tool or editor and ask while you work.

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)​

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": "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.** { *; }

  # The App Set ID is read only when Google Play services is already present in
  # the app, so R8 must not fail the build when these classes are missing.
  -dontwarn com.google.android.gms.appset.**
  -dontwarn com.google.android.gms.tasks.**
  -keep class com.google.android.gms.appset.** { *; }
  -keep class com.google.android.gms.internal.appset.** { *; }
note

The SDK does not require the External Dependency Manager for Unity (EDM4U) and pulls in no Android dependencies of its own. The android_app_set_id field is reported only when another SDK in your game already ships Google Play services.

1.5. Optional Add-on: Ad Revenue (ILRD)​

To receive the revenue of every ad impression from your ad mediation SDK (Unity LevelPlay, AppLovin MAX, AdMob, etc.), import the separate ILRD add-on package. It is not included in the main SDK (regardless of install method):

  • Get the latest GA_ILRD_UNITY.unitypackage using the following link.
  • Alternatively, download a specific version: https://download.gameanalytics.com/unity/[VERSION]/GA_ILRD_UNITY.unitypackage

Import it via Assets > Import Package > Custom Package, then follow the Ad Revenue (ILRD) guide to subscribe to your ad network's impressions.

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.