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.configureBuild("0.1.0")
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.
gameAnalytics.configureAutoDetectAppVersion(true);
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.configureUserId("my_user_id");
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("my_ext_uid")
Configure Privacy
Randomize the user id
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 use a random id regardless of the platform:
gameAnalytics.useRandomizedId(true)
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)
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.
gameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"])
The following limitations apply:
- You can have a maximum of 20 resource types
- Each resource currency string can only contain letters (e.g:
[A-Za-z]).
Item Types
Additionally resource events will require an item type.
You can only submit resource events using item types that have been registered in the configuration.
Any item type not included in this list will be rejected by the SDK.
gameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"])
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.
Any value which is not defined will be ignored!
In code you can call the following functions to set the available custom dimensions:
gameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"])
gameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"])
gameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"])
After creating a whitelist of available custom dimensions, you can set up one of the allowed values for the current user:
gameAnalytics.setCustomDimension01("ninja")
gameAnalytics.setCustomDimension02("whale")
gameAnalytics.setCustomDimension03("horde")
| Field | Type | Required | Description |
|---|---|---|---|
| customDimension | string | yes | One of the available dimension values set previously. Will persist cross session. Set to null to remove again. |
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:
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.
To start a session you will need to call the next function before being able to track events:
gameAnalytics.startSession()
# ...play the session and send events
gameAnalytics.endSession()
Error Submission
You can enable error submissions to catch error and exception messages within Godot 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
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.
gameAnalytics.setEnabledErrorReporting(true)