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.
gameanalytics::GameAnalytics::configureBuild("0.10");
User ID
In order to identify users and keep track of events, GameAnalytics will issue a random 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).
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::GameAnalytics::configureUserId("my_unique_user_id_24353245");
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::GameAnalytics::configureExternalUserId("myExternalUserId");
Configure Privacy
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::GameAnalytics::setEnabledEventSubmission(false);
By default event submission is 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.
gameanalytics::GameAnalytics::addResourceEvent(EGAResourceFlowType::Source, "diamonds", 100, "diamonds", "big_pack_01");
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.
Example:
gameanalytics::GameAnalytics::configureAvailableResourceCurrencies({"diamonds"});
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
Example:
gameanalytics::GameAnalytics::configureAvailableResourceItemTypes({"diamonds_pack_10000", "diamonds_pack_20000"});
Set Custom Dimensions
GameAnalytics supports the use of up to 3 custom dimensions:
Custom01Custom02Custom03
During the game it is possible to set the active value for each custom dimension dynamically. Once a dimension is set it will be persisted across sessions/game-start and automatically be added to all event categories.
Remember you have to set the custom dimensions before initialzing the SDK (but after setting the available custom dimensions) to be able to add the dimensions to the first session start event.
During gameplay it is possible to set values for 3 different custom dimensions. For each custom dimension it is needed specify a whitelist.
gameanalytics::GameAnalytics::setCustomDimension01("ninja");
gameanalytics::GameAnalytics::setCustomDimension02("dolphin");
gameanalytics::GameAnalytics::setCustomDimension03("horde");
gameanalytics::GameAnalytics::setCustomDimension03(""); // reset custom dimension 3
Read more about custom dimensions here.
| Field | Type | Description | Example |
|---|---|---|---|
| customDimension | string | One of the available dimension values set in the configuration phase. Will persist cross session. Set to empty string to reset. | "ninja" |
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:
constexpr const char* fields = "{\"test\": 1000, \"tests\": \"hello_world\"}";
gameanalytics::GameAnalytics::setGlobalCustomEventFields(fields);
| Field | Type | Description | Example |
|---|---|---|---|
| customFields | json string | 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.
On UWP a new session will start once the game is launched (or when the app is “resuming”). A session will end once the game is suspended.
On Windows, Linux and Mac, gameanalytics::GameAnalytics::onStop() should be called manually before quiting the game to create an end session event.
Session start
Generate new session and adds a session start event (a “user” event). Starts the periodic activation of submitting queued events.
Next event submit will fix potential missing session_end from earlier sessions.
Session end
Stop the periodic activation of submitting queued events. Adds a session_end event. Submit queued events. Should be called when the application is closed.
To ensure the background thread of the SDK will not continue running after the application has closed you need to call:
gameanalytics::GameAnalytics::onQuit();
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 you can use the following function:
gameanalytics::GameAnalytics::setEnabledManualSessionHandling(true);
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 is completely paused.
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::GameAnalytics::startSession();
To manually end the session and flush remaining events you will need to call:
gameanalytics::GameAnalytics::endSession();
Error Submission
You can enable error submissions to catch error and exception messages 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.
gameanalytics::GameAnalytics::setEnabledErrorReporting(true);
Custom Error Event Submission
To submit custom error events you can use the following function:
gameanalytics::GameAnalytics::addErrorEvent(EGAErrorSeverity::Critical, ""failed to load level"");