Stencyl SDK

The Stencyl SDK include platform support for iOS and Android.

Requirements

Stencyl: 3.1+

Haxe 3.1.3+

iOS: iOS 7+

Android: Android API Level 14

Build size

The download size differ from the actual build size. The additional size of adding GameAnalytics depend on the platform, but it is often very low. For Android it could be as low as 50kb depending on what standard libraries are already included in the game/app.

Alternative installation process

Configuring your game(s)

Copy link to clipboard

Game Key + Secret Key

For each platform you will need to have a game key and a secret key that will be used during the initialise process. Sign up and go get your keys if you did not have a chance to do it already by this stage.

ℹgame key is a unique identifier for your game.secret key is used to protect event data from being tampered with as it travels to the GameAnalytics servers.

Build

Build is used to specify the current version of your game. Recommended to use a 3 digit version like [major].[minor].[patch]. Notice there is a specific entry for each platform:

Custom Dimensions

During gameplay it is possible to set values for 3 different custom dimensions. For each custom dimension it is needed specify a whitelist. You cannot set a custom dimension value unless it is specified in the whitelist first.

The dimensions are comma-seperated like shown in the example (remember no space in between each entry):

Resource Currency and Item Types

When submitting resource events you specify a resource currency and resource item type. It is needed to specify a whitelist for each of these. You cannot submit a resource event using other values than specified here.

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

The currencies and item types are comma-seperated like shown in the example (remember no space in between each entry):

Use of a custom ID

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

ℹ
When using custom id you need to remember GameAnalytics will first be fully initialized when you have set the custom id. No events can be sent before GameAnalytics is fully initialized.

You can set the custom user ID as in the following example:

Use manual session handling

To enable manual session handling, add the following at the beginning of the game (in the when created block preferably):

Logging

The info log will output basic information about what is happening when your game is built for native. The verbose log will output the event JSON data that is being sent to the GameAnalytics servers when your game is built for native.

You can enable them as in the following examples:

#

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.

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. Read more about configuration here.

Initialize call will start the SDK and activate the first session. In order to initialise the SDK you will need to include the following blocks into your (early) code blocks.

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

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.

#

Business

Copy link to clipboard

Business events are used to track in-app purchases with real money.

ℹ
Mobile games can be hacked and distributed illegally.
Hacking an app will often involve faking/simulating all purchase requests. This will result in several Business events being sent to GameAnalytics for transactions that never occurred.

GameAnalytics provide the option of receipt validation for each purchase sent to GA servers. This process can ensure that revenue metrics reflect the actual spending in your game.

⚠
Some configuration is needed before receipt validation will be active.
Read information about validation and requirements for different platforms here.

Receipt validation in Stencyl is supported for the following stores.

App Store (iOS)

Google Play Store (Android)

The following blocks should be used for sending business events:

#

Resource

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.

Sink (subtract)resource events are instrumented with the flow type sink:

⚠
Be careful 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.

Progression

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.

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.

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

#

command center

Copy link to clipboard

#

How to use it

Copy link to clipboard

It can take up to a few seconds until the SDK manages to retrieve all the declared configurations for the game in the web tool. As a result, sometimes early calls for values of keys can return null. In order to avoid this, you can use the following check before fetching any config:

For retrieving a remote config the SDK provides the following block:

A similar block can be used with a fallback value in case there is no config associated to the given key:

Next, we can see an example of a block that activates when an Actor is clicked. The block checks if the Command Center has loaded the remote configs and sends a design event to GameAnalytics with the config value as the event_id. The key used is “soda” and the fallback default value is “Booster” which will be used if there is no key declared in the web tool for the given key:

#

Configs

Copy link to clipboard

For more information on Configs in general please click HERE (INSERT LINK).

#

Experiments (A/B testing)

Copy link to clipboard

For more information on Experiments (A/B testing) in general please click HERE (INSERT LINK).

#

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.

how does it work?

Copy link to clipboard

#

Session Handling

Copy link to clipboard

By default the SDK will handle session start/end automatically, but it is also possible to manually control this yourself.

⚠
Be aware that the initialization will always automatically start the first session even with manual session handling. If you are using ads in your game there is a big possibility that the onPause() and onStop() events will be triggered when the ads are showing which will interfere with the session length for information on how to fix this to look here

Automatic session handling

The automatic session handling will track the focused time the user is spending in your game – from game launch to the user leaving the game.

session start
On Android a new session will start once the game is launched or when the app is resumingif there is no current session.

session end
A session will end once the game is going to homescreen (or is not visible anymore).

It will end the session at once if the application received the onStop event from the game activity. It can also end the session if onPause event was received and 90 seconds have passed (sometimes only the onPause will trigger even though the user left the app).

Manual session handling

The automatic session handling only works if the game is contained in one activity.

It will then handle session end and start based on the events on that single activity. This behavior is common (having one activity) but some games define multiple activities and this automatic session handling will not work in an optimal way.

If your game does have multiple activities (or you just want to be in control when to start and end sessions) you can enable/disable manual session handling by calling this at any given time:

You will then need to call endSession and startSession at the appropriate times.

⚠
With manual session handling it is recommended to also call endSession when the game activity event onStop is fired. This will ensure a correct session close when users click the home or on/off button.

endSession()

This will end a session if:

manual session handling is enabled

a session is active

SDK is initialized (initialize will start a session automatically)

startSession()

This will start a new session if:

manual session handling is enabled

SDK is initialized (initialize will start a session automatically)

If a current session is active then it will end the current session and start a new one.

Handling ads and preserve correct session length

Ads will most likely trigger onPause() and onStop() which will interfere with the session length of the game. To prevent this you need to use manual session handling at least when you are about to show ads.

If you are already using manual session handling from the beginning of your game then you don’t need to worry about this.

setup

Copy link to clipboard

#

Event Queue

Copy link to clipboard

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

Interval

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.

Offline

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

For the Android platform 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 configureBuild is required to be called before initialize is completely finished. The design event call is required after initialise is finished. The queuing will make sure that each task is completely finished before proceeding to the next one.