Skip to main content

Setup

Download and Installation​

The first step is to download the latest version of our SDK from here.

Versions​

info

GameAnalytics.js includes local logging to the console and is 65Kb in size.

info

GameAnalytics.min.js is without logging and is 53Kb in size. It is recommended to initially use GameAnalytics.js while implementing the needed tracking.

This will make it easier to verify correct SDK instrumentation. When done it is possible to switch to GameAnalytics.min.js in production if it is needed to save the extra kilobytes.

Unzip the downloaded .zip and include this in your project (the files are located in the dist folder):

<script src="/path/to/GameAnalytics.js" />

NPM Install​

If you use node packages you can also install the SDK via npm: npm install gameanalytics.

npm install gameanalytics

And use it like this:

var gameanalytics = require("gameanalytics");
gameanalytics.GameAnalytics.setEnabledInfoLog(true);
caution

The SDK still expects to be run in a browser environment where the navigator object is defined

The JavaScript GA Snippet​

It is also possible to use the following snippet to asynchronously load GameAnalytics SDK when your website loads and still be able to configure, initialize and send events before the SDK is fully loaded (just like you can do with Google Analytics). The code should be added near the top of the tag and before any other script or CSS tags:

<!-- GameAnalytics -->
<script>
(function(w,d,a,m){var s='script';var g='GameAnalytics';w[g]=w[g]||function(){(w[g].q=w[g].q||[]).push(arguments)},a=d.createElement(s),m=d.getElementsByTagName(s)[0];a.async=1;a.src='http://download.gameanalytics.com/js/GameAnalytics-[VERSION].min.js';m.parentNode.insertBefore(a,m)})(window,document);

GameAnalytics("setEnabledInfoLog", true);
GameAnalytics("initialize", "GAME_KEY", "SECRET_KEY");
</script>
<!-- End GameAnalytics -->

The above code does four main things:

Creates a script element that starts asynchronously downloading the GameAnalytics.js JavaScript library from http://download.gameanalytics.com/js/GameAnalytics-[VERSION].min.js (replace [VERSION] with the latest or desired version of the SDK)

Initializes a global GameAnalytics function (called the GameAnalytics() command queue) that allows you to schedule commands to be run once the GameAnalytics.js library is loaded and ready to go.

Adds a command to the GameAnalytics() command queue to enable info logging.

Adds another command to the GameAnalytics() command queue to initialize the SDK (replace GAME_KEY and SECRET_KEY with your actual keys).

Command Queue​

The JavaScript GA snippet defines a global ga function known as the “command queue”.

It’s called the command queue because rather than executing the commands it receives immediately, it adds them to a queue that delays execution until the GameAnalytics.js library is fully loaded.

In JavaScript, functions are also objects, which means they can contain properties. The GA snippet defines a q property on the GameAnalytics function object as an empty array.

Prior to the GameAnalytics.js library being loaded, calling the ga() function appends the list of arguments passed to the GameAnalytics() function to the end of the q array.

For example, if you were to run the GA snippet and then immediately log the contents of GameAnalytics.q to the console, you’d see an array, two items in length, containing the two sets of arguments already passed to the GameAnalytics() function: console.log(GameAnalytics.q);

// Outputs the following:
// [
//   ['setEnabledInfoLog', true],
//   ['initialize', 'GAME_KEY', 'SECRET_KEY']
// ]

Once the GameAnalytics.js library is loaded, it inspects the contents of the GameAnalytics.q array and executes each command in order. After that, the GameAnalytics() function is redefined, so all subsequent calls execute immediately.

This pattern allows developers to use the GameAnalytics() command queue without having to worry about whether or not the analytics.js library has finished loading. It provides a simple, synchronous-looking interface that abstracts away most of the complexities of asynchronous code.

Adding Commands To The Queue​

All calls to the GameAnalytics() command queue share a common signature. The first parameter, the “command”, is a string that identifies a particular GameAnalytics.js method. Any additional parameters are the arguments that get passed to that method.

The rest of the documentation will refer to how to call methods unsing the traditional way and using the GameAnalytics() command queue.

Build-Settings​

tip

You only need to read this is your are interested in modifying and building the SDK from Typescript source. If you aren’t you can skip this section.

Dependencies​

  • Node.js
  • Gulp

Run the following command to install all devDependencies:

npm install

All source code (Typescript) is located in src and resulting distribution files from building are placed in dist.

To build run the following command:

gulp

This will build GameAnalytics.d.ts (declaration file), GameAnalytics.debug.js (includes sourcemap, not uglified), GameAnalytics.js (logging included, uglified, around 65Kb in size) and GameAnalytics.min.js (no logging included, uglified, around 53Kb in size).

Alternatively you can just build one of the targets by running one of these commands:

  • gulp normal
  • gulp debug
  • gulp mini
  • gulp declaration

Logging​

If you want to build the mini-release without logging included to save on the build size you can add the –nologging argument:

gulp mini --nologging

Testing​

To run the test, run:

gulp test

Initialize the SDK​

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
tip

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

info

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

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

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

Remember to add this line to the html file whenever you need to call the SDK.

<script src="/path/to/GameAnalytics.js">// <![CDATA[

<!-or-->

<script src="/path/to/GameAnalytics.min.js" />

Configuration​

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 [major].[minor].[patch] (e.g 1.2.0).

<!-- Traditional way -->
gameanalytics.GameAnalytics.configureBuild("android 1.0.0");

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:

<!-- Traditional way -->
gameanalytics.GameAnalytics.configureUserId("user1234567879");

Specifying Allowed Values​

For certain types it is required to define a whitelist containing possible unique values during the configuration phase.

caution

When the SDK is being used (after initialization) only the specified values will be allowed. A max 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.

<!-- Traditional way -->
gameanalytics.GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"]);
gameanalytics.GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);
gameanalytics.GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
gameanalytics.GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
gameanalytics.GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);
info

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

Enable/disable event submission​

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

gameanalytics.GameAnalytics.setEnabledEventSubmission(false);
// or
GameAnalytics("setEnabledEventSubmission", false);
info

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 Method​

Call this method to initialize using the game key and secret key for your game:

<!-- Traditional way -->
gameanalytics.GameAnalytics.initialize("[game key]", "[secret key]");
tip

Don’t have any keys yet? Head over here and register your game at the GameAnalytics website!

You can then find your game’s keys within the game settings.

Below is a common example of the code placed in a script lets call it main.js:

<!-- Traditional way -->
function onStart(){
    // ... other code from your project ...


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

    gameanalytics.GameAnalytics.configureBuild("0.10");

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

    gameanalytics.GameAnalytics.initialize("[game key]", "[secret key]");
}