Skip to main content

Configuration

GameAnalytics provides multiple features and options that need to be configured before initializing 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]

info

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.10"];

User ID​

In order to identify users and keep track of events, GameAnalytics will use the identiferForVendor (IDFV) as the default user id. This is a unique identifier for the app vendor and will be the same for all apps from the same vendor on the device.

It is recommended that you enable the option to use a randomized user id if you do not want to use the IDFV.

Set a Randomized User ID​

If this options is enabled, the SDK will generate a random unique user id 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). You can enable this option by calling the following function:

[GameAnalytics useRandomizedId:YES];
warning

The user id must be configured before initializing the SDK and cannot be changed afterwards.

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_unique_user_id_24353245"];
warning

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

tip

Read more about the external user id here

You can set the external user id by calling the following function:

[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 setEnabledEventSubmission:NO];
info

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 addResourceEventWithFlowType:GAResourceFlowTypeSource currency:@"diamonds" amount:@100 itemType:@"diamonds" itemId:@"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 must only use resource currencies that have been registered in the configuration. Attempting to submit a resource event with a currency not include in the configured list will result in the event being rejected by the SDK.

Example:

[GameAnalytics configureAvailableResourceCurrencies:@[@"diamonds"]];
warning

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

warning

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 configureAvailableResourceItemTypes:@[@"diamonds_pack_10000", @"diamonds_pack_20000"]];

Set Custom Dimensions​

GameAnalytics supports the use of up to 3 custom dimensions:

  • Custom01
  • Custom02
  • Custom03

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 initializing 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 to specify a whitelist.

[GameAnalytics setCustomDimension01:@"ninja"];
[GameAnalytics setCustomDimension02:@"dolphin"];
[GameAnalytics setCustomDimension03:@"horde"];

[GameAnalytics setCustomDimension03:@""]; // reset custom dimension 3
tip

Read more about custom dimensions here.

FieldTypeDescriptionExample
customDimensionstringOne of the available dimension values set in the configuration phase. Will persist cross session. Set to empty string to reset."ninja"

To reset a custom dimension during a session simply set the dimension name to nil.
For instance, to reset the custom dimension01 the following call needs to be written:

// Swift
GameAnalytics.setCustomDimension01(nil)

Custom Event Fields​

Custom event fields are a set of key-value pairs that can be added to any event in order to attach extra information.

tip

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 any time during the game.

info

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:

NSString *fields = @"{\"test\": 1000, \"tests\": \"hello_world\"}";
[GameAnalytics setGlobalCustomEventFields:fields];
FieldTypeDescriptionExample
customFieldsjson stringA set of key-value pairs. Values can be strings or numbers{
"test": 1000,
"tests": "hello_world"
}
caution

There is a limit of using 50 custom event fields per event, keys can max consist of 64 characters and values (when strings) can max consist of 256 characters.

caution

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 iOS, 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.

To ensure the background thread of the SDK will not continue running after the application has closed you need to call:

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

caution

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 manually enable or disable session handling you can use the following function:

[GameAnalytics setEnabledManualSessionHandling:YES];

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.

tip

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

info

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 setEnabledErrorReporting:YES];

Custom Error Event Submission​

To submit custom error events you can use the following function:

[GameAnalytics addErrorEventWithSeverity:GAErrorSeverityCritical message:@"failed to load level"];