Skip to main content

Configuration

GameAnalytics provides multiple options that can be configured before initializing the SDK.

Set the Build Version​

The build version identifies the current release of your game. Use a 3-digit version string: [major].[minor].[patch].

// Set build version
GameAnalytics.configureBuild("android 1.0.0");

You can also enable auto-detection of the app version instead of setting it manually:

GameAnalytics.configureAutoDetectAppVersion(true);

User ID​

The SDK automatically generates a user ID for each player. This is sufficient for most use cases.

Set a Custom User ID​

You can supply a custom user ID — for example, to match your internal user database:

GameAnalytics.configureUserId("user1234567879");
caution

User ID must be configured before initializing the SDK. Changing it after deployment will cause existing users to be counted as new users.

Set an Optional External User ID​

An external user ID can be set independently of the internal user ID. It has no influence on internal GameAnalytics processes and is simply appended to all events for cross-referencing with external systems:

GameAnalytics.configureExternalUserId("external_user_id");

Configure Privacy​

Control Event Submission​

To disable event submission (e.g. for GDPR compliance), call:

GameAnalytics.setEnabledEventSubmission(false);
info

By default event submission is enabled. You will still receive remote configs even after disabling event submission.

Resources​

Resource events track the flow of virtual currencies in your game. Before using them, you must register the currencies and item types your game uses.

GameAnalytics.addResourceEventWithFlowType(GAResourceFlowType.Source, "Gems", 400, "IAP", "Coins400");

Currencies​

Register all virtual currencies before initializing the SDK. Only registered currencies will be accepted in resource events.

GameAnalytics.configureAvailableResourceCurrencies("gems", "gold");
info

Each resource currency string should only contain [A-Za-z] characters.

Item Types​

Register all item types before initializing the SDK. Only registered item types will be accepted in resource events.

GameAnalytics.configureAvailableResourceItemTypes("boost", "lives");
danger

A maximum of 20 values are allowed for each list. Games with too many unique values may be blocked.

Set Custom Dimensions​

GameAnalytics supports up to 3 custom dimensions (Custom01, Custom02, Custom03).

Custom dimensions persist across sessions and are attached to all events. Set the available values before initializing, and set the active value before or during gameplay.

// Configure available values (before init)
GameAnalytics.configureAvailableCustomDimensions01("ninja", "samurai");
GameAnalytics.configureAvailableCustomDimensions02("whale", "dolphin");
GameAnalytics.configureAvailableCustomDimensions03("horde", "alliance");
// Set active values (during gameplay)
GameAnalytics.setCustomDimension01("ninja");
GameAnalytics.setCustomDimension02("dolphin");
GameAnalytics.setCustomDimension03("horde");

To reset a custom dimension, set it to empty string or null:

GameAnalytics.setCustomDimension01("");
GameAnalytics.setCustomDimension02(null);
tip

Read more about Custom Dimensions here.

Custom Event Fields​

Custom event fields are key-value pairs that can be attached to any event for additional context. They are only available via raw data export (PipelineIQ).

HashMap<String, Object> fields = new HashMap<>();
fields.put("test", 100);
fields.put("test_2", "hello_world");

GameAnalytics.addDesignEventWithEventId("BossFights:FireLord:KillTimeUsed", 234, fields);
caution

There is a limit of 50 custom event fields per event. Keys can have a maximum of 64 characters and string values a maximum of 256 characters.

tip

Find more information on Custom Event Fields following the link.

Session Handling​

By default, the SDK handles sessions automatically. A session starts when the app is launched or resumed, and ends when it goes to the background.

Manual Session Handling​

If you need full control over when sessions start and end, enable manual session handling:

GameAnalytics.setEnabledManualSessionHandling(true);

Then start and end sessions manually:

GameAnalytics.startSession();
GameAnalytics.endSession();
caution

By using manual session handling you are responsible for deciding when sessions begin and end. Incorrect setup will result in inaccurate metrics.

Error Submission​

By default, the SDK automatically sends error events for uncaught exceptions. You can disable this:

GameAnalytics.setEnabledErrorReporting(false);

It is also possible to submit custom error events — see Error Events for details.