Setup

Download and Installation

The Cordova SDK can be downloaded directly from our github repo or via npm

From your terminal go to your project's root folder and execute:

cordova plugin add cordova-plugin-gameanalytics
cordova plugin add cordova-plugin-device

For iOS you need to have Cocoapods installed for the plugin to be able to build for iOS platform.

Now we should be ready for adding code to activate the SDK! There are 3 phases the SDK will go through.

• configuration
• initialization
• adding events or changing dimensions

Configuration calls configure settings for the SDK and some will not be able to be altered after initialize has been called.

Initialize call will start the SDK and activate the first session.

The configuration and initialization steps should be called when the application starts.

Once step 1 & 2 is done you can add events at different parts of the game code where some relevant action is happening.

Configuration

The configuration phase happens before initialization is called. The available configuration options are listed here.

• build
• custom userId
• available (allowed) custom dimensions
• available (allowed) resource currencies
• available (allowed) resource item types

Build

Build is used to specify the current version of your game. Specify it using a string. Recommended to use a 3 digit version like this: [major].[minor].[patch]

GameAnalytics.configureBuild("0.1.1");

Auto detect build version

There is an option to auto detect app version to use for build field. Just call this before intializing the SDK:

GameAnalytics.configureAutoDetectAppVersion(true);

Custom userId

The SDK will automatically generate a user id and this is perfectly fine for almost all cases.

Sometimes it is useful to supply this user_id manually – for example if you download raw data for processing and need to match your internal user id (could be a database index on your user table) to the data collected through GameAnalytics. Do not use a custom userId unless you have a specific need for using it.

info

Note that if you introduce this into a game that is already deployed (using the automatic id) it will start counting existing users as new users and your metrics will be affected. Use this from the start of the app lifetime when you need.

GameAnalytics.configureUserId("my_user_id");

Specifying allowed values

For certain types it is required to define a whitelist containing possible unique values during the configuration phase. When the SDK is being used (after initialization) only the specified values will be allowed. A maximum of 20 values are allowed for each list.

danger

Processing many unique dimension values can be taxing for our servers. A few games with a poor implementation can seriously increase our cost and affect stability. Games will be blocked if they submit too many unique dimension values. We have this configuration requirement to guide users into planning what dimension values can be used.

GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);
GameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"]);
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);

Enable/disable event submission

If you for GDPR purposes need to disable event submission you can call the following:

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.

Initializing

Once all the configurations have been made the SDK needs to be initialized by calling this method using the game key and secret key for your game:

GameAnalytics.initialize({
    gameKey: [game key]",
    secretKey: "[secret key]
});

tip

Don’t have any keys yet?

Head over here and register your game at the GameAnalytics website!

Here's an example of the whole initialization process:

onDeviceReady: function(){
    // ... other code from your project ...

    GameAnalytics.setEnabledInfoLog(true);
    GameAnalytics.setEnabledVerboseLog(true);

    GameAnalytics.configureBuild("0.1.1");

    GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
    GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
    GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);
    GameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"]);
    GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);

    GameAnalytics.initialize({
        gameKey: "[game key]",
        secretKey: "[secret key]"
    });

}