Setup

Unity Package Manager

This SDK can be installed using the unity package manager system (on Unity 2018.3+) with git. Alternatively you can install the SDK using the traditional unity packages.

• Download the latest version of External Dependency Manager for Unity (pick .tgz) from here and install it like described here
• In your unity project root open ./Packages/manifest.json
• Add the following line to dependencies section "com.gameanalytics.sdk": "[latest_version]"
• Add the following to scopedRegistries section:

"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"
      ]
    }
  ]

• Open Unity and the package should download automatically
• OBS: If you want to use ILRD with the SDK you need to download this .unitypackage here

Traditional Unity Packages

You can download the SDK as a .unitypackage from here. It is also possible to download a specific version of a .unitypackage by using the following url format: https://download.gameanalytics.com/unity/[VERSION]/GA_SDK_UNITY.unitypackage

• In the Unity editor go to Assets > Import Package > Custom Package

  

• Browse to the package location on your hard disk

• Leave all the files checked and click Import

tip

Check that the Unity environment has been already configured with the modules for the platforms you are targeting.

tip

If you are targeting iOS, this is a good time to go to File > Build Settings > iOS and make sure the iOS module is loaded and you can create iOS builds.

Sign Up and Login

1. Access Settings

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

2. Account Creation

If you have not already, you can register for a GameAnalytics accounts via our online form here or via the Settings menu in the Unity editor.

After you have signed up you will be asked to create a studio and a game. If your game is already published and on an app store you can search for it using the provided search field or else you can create it manually.

3. Login

• Click the Login button in Settings and enter your credentials.
• 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.

info

Don’t have any keys yet? Head over here and register your game at the GameAnalytics website! You can then find your game’s keys within the game settings.

IDFA Consent Status

From iOS 14+ devices the SDK will track IDFA consent status on all events. To track this properly you need to make sure you have shown the IDFA consent dialog before initializing the SDK. It is important to still initialize the SDK even if the user doesn't authorize to use IDFA:

  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.

If you don't need to use IDFA and you don't have any third party SDKs that need to use IDFA then you don't need to show the IDFA consent dialog (you need to use v6.6.4 or later of the Unity SDK). The GameAnalytics Unity SDK uses IDFV (for iOS) as the user id and it will only add IDFA to events if IDFA consent status is authorized.

Initializing 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).

The 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.

Creating a GameAnalytics GameObject

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

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.

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.

When to log events

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.

Custom User id

• The SDK will automatically generate a user id and this is perfectly fine for almost all cases.
• Sometimes it is useful to supply this 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.
• 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.

Proguard (Android only)

If your app 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{*; }