Docs > Construct SDK

Construct SDK



Copy link to clipboard


Download & Installation

Copy link to clipboard

Github Repository

Use the download button below to download SDK files from Github.

Construct 2

Unzip the downloaded .zip and drag and drop the gameanalytics.c2addon file into your Construct 2 project and accept the installation of the plugin.

Construct 3

Unzip the downloaded .zip and open your Construct 3 project, click Menu -> View -> Addon manager -> Install new addon…, select the gameanalytics.c3addon file and accept the installation of the plugin.

Remember you need to restart Construct before you can start using the GameAnalytics plugin.

Cordova export

When exporting for Cordova remember to call cordova plugin add cordova-plugin-gameanalytics and cordova plugin add cordova-plugin-device in the exported Cordova project (since v2.0.2 this is not needed to do anymore for Construct 3). Remember to select Cordova project when exporting and not Xcode project as it has only been tested with the “Cordova project” option.

Remember the GameAnalytics Constructor plugin doesn’t work in “Worker Mode”.


initialize sdk

Copy link to clipboard

Using the SDK

Copy link to clipboard

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

  1. configuration
  2. initialization
  3. 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.

Remember to add the GameAnalytics object to the project before you can use the SDK:

  1. Right-click on Object types
  2. Click on Insert New Object
  3. Choose GameAnalytics (under Analytics category)
  4. Click on Insert


Copy link to clipboard

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

Set the build version by selecting the GameAnalytics object editing the value under the Properties section, then it will automatically be set when initializing the SDK.

Auto detect app version to use for build field
There is an option to auto detect app version to use for build field (only for corodova export). Just enable it in the Properties section.

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.

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

Set the custom user id by selecting the GameAnalytics object editing the value under the Properties section, then it will automatically be set when initializing the SDK.

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. 20 values are allowed for each list.

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.

Use the following actions to be able to configure allowed values:

  • Add currency to available resource currencies
  • Add currency to available resource item types
  • Add currency to available custom 01 dimensions
  • Add currency to available custom 02 dimensions
  • Add currency to available custom 03 dimensions

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 action:

Toggle event submission

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.



Copy link to clipboard

Call this action to initialize the SDK:

Remember to set the game key and secret key for your game in Properties section on the GameAnalytics object. The initialize action will also set the info and verbose log, manual session handling and build version based on the values set in the properties section:

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

Below is a common example of the actions called from the On start of layout:


adding events

Copy link to clipboard


Copy link to clipboard

GameAnalytics feature the following event types.

Event Description
Business In-App Purchases supporting receipt validation on GA servers.
Resource Managing the flow of virtual currencies – like gems or lives.
Progression Level attempts with Start, Fail & Complete event.
Error Submit exception stack traces or custom error messages.
Design Submit custom event id’s. Useful for tracking metrics specifically needed for your game.

Event id’s are strings separated by colons defining an event hierarchy – like "kill:robot:large". It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.

A bad implementation example.

level_name could be 100 values, weapon_used could be 300 values and damage_done could be 1-5000 perhaps. This will generate an event hierarchy with:

100 * 300 * 5000 = 150M possible nodes.

This is far too many. Also the damage should be put as a value and not in the event string. The processing will perhaps be blocked for a game doing this and cause other problems when browsing our tool.

The maximum amount of unique nodes generated should be around 10k.

Please read our event guide here.
You will get the most benefit of GameAnalytics when understanding what and how to track.



Copy link to clipboard

Business events are used to track real-money transactions.

Field Type Description Example
currency string Currency code in ISO 4217 format.
amount integer Amount in cents. 99 is 0.99$
itemType string The type / category of the item. GoldPacks
itemId string Specific item bought. 1000GoldPack
cartType string The game location of the purchase.
Max 10 unique values.

For more information about the business event go here.



Copy link to clipboard

Resource events are used to register the flow of your in-game economy (virtual currencies) – the sink (subtract) and the source (add) for each virtual currency.

Before calling the resource event it is needed to specify what discrete values can be used for currencies and item types in the Configuration phase.

source (add) Gem currency from an in-app purchase. 

sink (subtract) Gem currency to buy an item. 

sink (subtract) Gem currency to source (buy) some amount of another virtual currency (BeamBooster). 

sink (subtract) 3 BeamBooster currency that were used during a level. 

Field Type Description Example
flowType enum A defined enum for sourcing and sinking resources. Sink
currency string The resource type/currency to track. Has to be one of the configured available resource currencies.
This string can only contain [A-Za-z] characters.
Gems, BeamBoosters, Coins
amount float Amount sourced or sinked. 0 or negative numbers are not allowed. 100.0
itemType string For sink events it can describe an item category you are buying (Weapons) or a place (Gameplay) the currency was consumed. For source events it can describe how the currency was gained. For example “IAP” (for in-app purchase) or from using another currency (Gems). Has to be one of the configured available itemTypes. Weapons, IAP, Gameplay, Boosters
itemId string For sink events it can describe the specific item (SwordOfFire) gained. If consumed during Gameplay you can simply use “Consumed”. For source events it describes how the player got the added currency. This could be buying a pack (BoosterPack5) or earned through Gameplay when completing a level (LevelEnd). BoosterPack5, SwordOfFire, LevelEnd, Coins400

Be carefull to not call the resource event too often !

In a game where the user collect coins fairly fast you should not call a Source event on each pickup. Instead you should count the coins and send a single Source event when the user either complete or fail the level.

For more information about the resource event go here.



Copy link to clipboard

Progression events are used to track attempts at completing some part of a game (level, area). A defined area follow a 3 tier hierarchy structure (could be world:stage:level) to indicate what part of the game the player is trying to complete.

When a player is starting a progression attempt a start event should be added.
When the player then finishes the attempt a fail or complete event should be added along with a score if needed.

Add a progression start event.

It is not required to use all 3 if your game does not have them.

  • progression01
  • progression01 and progression02
  • progression01 and progression02 and progression03
Field Type Description Example
progressionStatus enum Status of added progression Start
progression01 string Required progression location. World01
progression02 string Not required. Use if needed. Stage01
progression03 string Not required. Use if needed. Level01
score integer An optional score when a user completesor fails a progression attempt. Remember to set progression02 and/or progression03 if they are not used when using score parameter. 1023

For more information about the progression event go here.



Copy link to clipboard

Used to track custom error events in the game. You can group the events by severity level and attach a message.

To add a custom error event call the following function: 

Field Type Description Example
severity enum Severity of error Debug
message string Error message (can be null) “Error when entering level12”

For more information about the error event go here.



Copy link to clipboard

Every game is special. Therefore some needed events might not be covered by our other event types. The design event is available for you to add your own event-id hierarchy.

Please note that custom dimensions and progression filters will not be added on design and error events. Therefore you cannot (at the moment) filter by these when viewing design or error metrics.

To add a design event call the following method.

It is also possible to add a float value to the event.
This will (in addition to count) make the mean and sum aggregation available in the tool.

Field Type Description Example
eventId string The eventId is a hierarchy string that can consist of 1-5 segments separated by ‘:’. Each segment can have a max length of 32. “StartGame:ClassLevel1_5”, “StartGame:ClassLevel6_10”
value float A float event tied to the eventId. Will result in sum & mean values being available. 34.5

It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.

A bad implementation example.

level_name could be 100 values, weapon_used could be 300 values and damage_done could be 1-5000 perhaps. This will generate an event hierarchy with:

100 * 300 * 5000 = 1.5M possible nodes.

This is far too many. Also the damage should be put as a value and not in the event string. The processing will perhaps be blocked for a game doing this and cause other problems when browsing our tool.

The maximum amount of unique nodes generated should be around 10k.

For more information about the design event go here.


remote configs

Copy link to clipboard



Copy link to clipboard

Product Update – Remote Configs

We are excited to announce the upcoming release of Remote Configs – our new tool that will replace Configs.

Remote Configs will be released in October 2019 with a new user interface and updated SDKs.

You can continue to use the current version of Configs. We will soon be sharing more information and our migration guide.

If you have any questions, please don’t hesitate to reach out.

To manual check if Remote Configs is ready (has been populated with values) you can call this:

Remember the remote configs can be populated with an empty dictionary if the device is offline and there are no cached remote configs from a previous session.

To get values out of a populated Remote Configs use the following methods:

If the specified key is not found in the Remote Configs it will return the default value either “normal” or “custom” default value.

For Cordova export
If you need to use configs in a Cordova export project you need to use callback functions to get the return value as the this asynchronous:

The function name parameter belongs to the Is RC ready conditions which is hidden on the picture but you just need to edit it to show it.

The callback functions can of course be called something else than in the example.


custom dimensions

Copy link to clipboard

Using Custom Dimensions

Copy link to clipboard

GameAnalytics support the use of 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 initialzing the SDK (but after setting the available custom dimensions) to be able to add the dimensions to the first session start event.

Setting each custom dimension. To reset a set custom dimension simply just set it to empty string.


Field Type Description Example
customDimension string One of the available dimension values set in the configuration phase. Will persist cross session. Set to empty string to reset. ninja

Read more about custom dimensions here.


debug & verify

Copy link to clipboard


Copy link to clipboard

The SDK is designed to be as silent as possible and use very few resources. You will therefore not get much information by default in your development console.

We have 2 different debug log types that can be enabled / disabled (at any time).

  • info log
  • verbose log

Info log

Short messages will be output when enabled explaining when some action is being performed by the SDK. Sometimes cropping text / values to make it more readable.

Enable info log when implementing the SDK (done in the properties of the GameAnalytics object) – remember to turn it off in production!

Info/GameAnalytics: Add DESIGN event: {eventId:someEvent, value:0}
Info/GameAnalytics: Add DESIGN event: {eventId:someOtherEvent, value:100}
Info/GameAnalytics: Add ERROR event: {severity:info, message:This is some in}

Verbose Log

Console output when each event is added (all fields) in JSON string format. This is the data being submitted to the GA servers for each event.

Enable verbose log when troubleshooting events (done in the properties of the GameAnalytics object).

This can result in a lot of text. When troubleshooting/debugging events it is therefore recommended to enable/disable when performing the action that need inspection.


Verify Implementation

Copy link to clipboard

Enable the Info Log to verify that events are being sent from your game project without any issues being reported.

Events submitted should register after a minor delay in our realtime dashboard in the GameAnalytics tool.

Read more about the realtime dashboard and our data processing.


how does it work?

Copy link to clipboard

Session Handling

Copy link to clipboard

Sessions are the concept of a user spending focused time in your game – from game launch to the user leaving the game.

Session start

  1. Generate new session.
  2. Add a session start event (a “user” event).
  3. Start the periodic activation of submitting queued events.
  4. Next event submit will fix potential missing session_end from earlier sessions.

Session end

  1. Stop the periodic activation of submitting queued events.
  2. Add a session_end event.
  3. Submit queued events.

Event Queue

Copy link to clipboard

Whenever an event is added (and validated) it will be added to a local database queue.


Every 8 seconds the SDK will start a task for submitting queued events since last submit. This processing is done in a separate low-priority thread that will have minimum impact on performance. The payload is gzipped and will therefore only consume a small amount of bandwidth.


When a device is offline the events are still added to the queue. When the device is online it will submit.


Thread Handling

Copy link to clipboard

Almost every piece of this code is run using a dedicated low-priority serial thread queue to avoid UI lag or sudden performance spikes.

The queue will execute each task sequentially. If the SDK add several tasks to the queue then each will be executed in turn. A task could be adding an event or submitting all queued events.

Consider this example with 3 calls.

The queuing will make sure that each task is completely finished before proceeding to the next one.


There is more!

Copy link to clipboard

There is much more to GameAnalytics and we suggest that you read our general documentation.

Please create a support ticket if you have any feedback like..

  • bugs
  • confusing features or UI
  • great ideas!

We hope you enjoy our service!

Contact support

Any queries about the platform are welcome.

Give article feedback

Let us know what you think about the articles.