Configuration
GameAnalytics provides multiple features and options that need to be configured before initialzing the SDK.
Set the Build Version
The build is used to specify the current version of your game. Specify it using a string. Recommended using a 3 digit version like [major].[minor].[patch]
The build version should be used for changing production builds of the game. We recommend creating a separate game when implementing or testing the SDK.
Automatically send the build number
This feature is only available for Android and iOS builds!
Instead of manually setting the build version, you can enable the Send Version as Build Number option, the app version will automatically be detected and used for the build field.
User ID
In order to identify users and keep track of events, GameAnalytics will issue an unique user id.
By default the GameAnalytics SDK will generate a default user for each user and requires no configuration (it will be assigned when the SDK is initialized for the first time and will persist across sessions).
The default user id depends on the platform:
| Platform | Default User Id |
|---|---|
| Android | Random Id |
| iOS | IDFV |
| Desktop (Windows, Linux, MacOS) | Random Id |
| WebGL | Random Id |
Set a Custom User ID
While the default user id will suffice for most use cases, you can also set a custom user id using the following function:
GameAnalytics.SetCustomId("myCustomUserId");
The user id must be configured before initializing the SDK and cannot be changed afterwards.
Set an optional External User ID
Besides the user id, GameAnalytics also supports an optional identifier called external user id which will be attached as to every event alongside the regular user id.
The external user id (unlike the normal user id) is not used internally by the GameAnalytics SDK, thus will not influence any metrics and can be changed anytime.
Read more about the external user id here
You can set the external user id by calling the following function:
GameAnalytics.SetExternalUserId("myExternalUserId");
Configure Privacy
Disable Advertising ID Tracking
If the app has the required permissions, GameAnalytics will track the advertising IDs on certain platforms such as Android and iOS.
If you wish to disable tracking, for privacy reasons, you can call the following function:
GameAnalytics.EnableAdvertisingIdTracking(false);
This function will also force the default generated user id to be fully random on all platforms
Control Event Submission
You can manually turn off/on event submission for GA events. This is useful if you need, for GDPR purposes, to disable event submission.
GameAnalytics.SetEnabledEventSubmission(false);
By default event submission is of course enabled. You will still receive configs if you have set any for your game even after disabling event submission.
Resources
When submitting resource events you will be required to specify a resource currency and resource item type. It is needed to specify a whitelist for each of these.
Currencies
If you want to track resource events you will first have to register currencies used inside your game before initializing the SDK. You cannot submit a resource event using other values than specified here in the settings.
The following limitations apply:
- You can have a maximum of 20 resource types
- Each resource currency string should only contain letters (e.g:
[A-Za-z]).
Item Types
Additionally resource events will require an item type. You cannot submit a resource event using other values than specified here in the settings.
The following limitations apply:
- You can have a maximum of 20 resource items
- Each resource currency string must only contain only alphanumeric characters
Set Custom Dimensions
Read more about custom dimensions here
GameAnalytics allows you to create up to 3 custom dimensions for your events. You will first have to set these up in your GA dashboard in Settings under the Setup tab.
Any value which is not defined in the dashboard will be ignored!
In code you can call the following functions to set the custom dimension for the current user:
// set custom dimension number 1
GameAnalytics.SetCustomDimension01("customDimension1");
// set custom dimension number 2
GameAnalytics.SetCustomDimension02("customDimension2");
// set custom dimension number 3
GameAnalytics.SetCustomDimension03("customDimension3");
| Field | Type | Required | Description |
|---|---|---|---|
| customDimension | string | yes | One of the available dimension values set in Settings (Setup tab). Will persist cross session. Set to null to remove again. |
Custom Event Fields
Custom event fields are a set of key-value pairs can be added to any event in order to attach extra information.
Read more about how to use Custom Event Fields here.
It is possible to set global custom event fields that will be attached to every event, those can be set at anytime during the game.
Custom fields attached to an event will overwrite global custom event fields as they take priority.
Here's an example of how you can set global custom fields for your game:
Dictionary<string, object> customFields = new Dictionary<string, object>();
customFields.Add("test", 1000);
customFields.Add("test_2", "global_hello_world");
GameAnalytics.SetGlobalCustomEventFields(customFields);
| Field | Type | Description | Example |
|---|---|---|---|
| customFields | dictionary | A set of key-value pairs. Values can be strings or numbers | { "test": 1000, "tests": "hello_world" } |
Custom event fields will not be available in the GameAnalytics dashboards.
They will only be visible while using Datasuite, either in Data Warehouse or Data Export.
Session Handling
Sessions are the concept of a user spending focused time in your game, from game launch to the user leaving the game.
When the session is active you will be able to track events (e.g: after the SDK hs been initialized) and the event queue will be running on a low priority thread, batching events and sending them to the server every 8 seconds.
By default GameAnalytics will automatically manage sessions for you. A session will start once the SDK has been initialized, the session end is marked either by the app going into background or closing the app. A new session will start if the application comes back into foreground.
Session lengths will be counted as playtime.
Manual Session Handling
The default session handling should suffice in most cases and it is recommended. However it is also possible to handle the session manually if necessary.
Do not use manual session handling unless it is absolutely necessary.
If sessions are not handled accurately this will result in inaccurate and skewed metrics being reported!
If enabled manual session handling will be enabled automatically just before initialization. To manual enable or disable session handling set the checkbox inside GameAnalytics → Select Settings → Advanced
When you are using manual session handling you are responsible to accurately start and end sessions, failing to do so will result in inaccurate and skewed metrics being reported.
With manual session handling it is recommended to also call endSession when the game activity event onStop is fired. This will ensure a correct session close when users click the home or on/off button.
To start a session you will need to call the next function before being able to track events:
GameAnalytics.StartSession();
To manually end the session and flush remaining events you will need to call:
GameAnalytics.EndSession();
Error Submission
You can enable error submissions to catch error and exception messages within Unity when the game is running and submit them to GameAnalytics. This is useful for discovering unforeseen issues after the game has been launched. It will submit an error event using the type error, warning or critical.
After a game has been launched it will only send a maximum of 10 error events automatically. Some games can generate a lot of exceptions and this cap will prevent degraded performance and unintended bandwidth usage.
Native Error Reporting
This feature is only available for Android and iOS!
If enabled the SDK will automatically send error event for native unhandled exceptions. In most cases the SDK can send the error event straight away when the app/game crashes but else the error event should be sent in next session.
