Integrations

Cocos2D SDK

Documentation for the GameAnalytics SDK for Cocos2D.

:bulb:
Do you have your game registered at the GameAnalytics website?
Head over here and get your game keys!

 

For more information about the GameAnalytics service please read our support pages.

If you have any feedback / questions / bugreports then please do not hesitate to contact our friendly support ninjas. :couple:

SETUP

Download & Installation

To download the SDK use this link or use the Download ZIP button from the repository.

Unzip the downloaded .zip and place folders in your Cocos2D project as described below.

C++

Copying files

Copy all the files/folders inside the Classes folder and paste them here:

  • [CPP_PROJECT_ROOT_FOLDER]/Classes

 

Copy the gameanalytics folder found inside the proj.android-studio/app/jni and paste it here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.android-studio/app/jni

 

Copy all the files inside the proj.ios_mac/ios folder and paste them here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.ios_mac/ios

 

Copy all the files inside the proj.ios_mac/mac folder and paste them here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.ios_mac/mac

 

Copy the libs folder inside the proj.win32 folder and paste it here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.win32

 

Copy the libs folder inside the proj.win10 folder and paste it here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.win10/[WIN10_PROJECT_NAME]

 

Copy the libs folder inside the proj.tizen folder and paste it here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.tizen

 

Copy the libs folder inside the proj.linux folder and paste it here:

  • [CPP_PROJECT_ROOT_FOLDER]/proj.linux

JS

Copying files

Copy all the files inside the js/src folder and paste it here:

  • [JS_PROJECT_ROOT_FOLDER]/src

 

Copy all the files/folders inside the js/frameworks/runtime-src/Classes folder and paste them here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes

 

Copy the gameanalytics folder found inside the proj.android-studio/app/jni and paste it here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.android-studio/app/jni

 

Copy all the files inside the proj.ios_mac/ios folder and paste them here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-srcproj.ios_mac/ios

 

Copy all the files inside the /proj.ios_mac/mac folder and paste them here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-srcproj.ios_mac/mac

 

Copy the libs folder inside the proj.win32 folder and paste it here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.win32

 

Copy the libs folder inside the proj.linuz folder and paste it here:

  • [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.linux

 

Modifying files

[JS_PROJECT_ROOT_FOLDER]/project.json

Add the following line in the jsList section:

  • “src/ga_enums.js”

 

[JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes/AppDelegate.cpp

Include the following header:

Add the following line in the applicationDidFinishLaunching() method:

Lua

Copying files

Copy all the files inside the lua/src folder and paste it here:

  • [LUA_PROJECT_ROOT_FOLDER]/src

 

Copy all the files/folders inside the lua/frameworks/runtime-src/Classes folder and paste them here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes

 

Copy the gameanalytics folder found inside the proj.android-studio/app/jni and paste it here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.android-studio/app/jni

 

Copy all the files inside the proj.ios_mac/ios folder and paste them here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-srcproj.ios_mac/ios

 

Copy all the files inside the /proj.ios_mac/mac folder and paste them here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-srcproj.ios_mac/mac

 

Copy the libs folder inside the proj.win32 folder and paste it here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.win32

 

Copy the libs folder inside the proj.linux folder and paste it here:

  • [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.linux

Modifying files

[LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes/AppDelegate.cpp

Include the following header:

Add the following line in the applicationDidFinishLaunching() method:

Cocos Creator (HTML5)

If you use Cocos Creator to build to HTML5 you can use our JavaScript SDK and install it like this by running the following command from the project root folder:

And use it like this:


Configure Android Studio

Modifying files

proj.android-studio/build.gradle

In the [PROJECT_ROOT_FOLDER]/proj.android-studio/build.gradle file add the following to the repository section (under allprojects).

In the same file you should make sure the following settings are at least supporting version 24 for your app.

 

proj.android-studio/app/build.gradle

In the [PROJECT_ROOT_FOLDER]/proj.android-studio/app/build.gradle file add the following to the dependencies section.

You can find the latest version of the Android library here.

 

proj.android-studio/app/jni/Android.mk

In the [PROJECT_ROOT_FOLDER]/proj.android-studio/app/jni/Android.mk add the following to LOCAL_SRC_FILES section.

Also add the following to the LOCAL_C_INCLUDES section.

 

Orientation change configuration

If your game can change orientation then each time this happens it will cause the activity to destroy and be recreated. This will create a new session in the SDK. To avoid this it is very important to add the following line along with your activity entry in the AndroidManifest.xml file

Here is an example of an activity entry inside the AndroidManifest.xml.

Configure Xcode

Open and modify the .xcodeproj file inside [PROJECT_ROOT_FOLDER]/proj.ios_mac/ with the following changes depending on platform being targetted.

iOS

  • Add libGameAnalytics.a and libsqlite3.tbd to Link Binary with Libraries
  • Add all .cpp, .mm and .h files from Classes and proj.ios_mac/ios to the project

OS X

  • Add all .a files inside the mac folder to Link Binary with Libraries
  • Add all .cpp and .h files from Classes and proj.ios_mac/mac to the project
  • Link to the following frameworks:
    • CoreFoundation
    • Foundation
    • CoreServices

Configure Visual Studio

Win32

  • Add all .lib files under proj.win32/libs as linker input under additional dependencies for both Debug and Release configurations
  • Add all .cpp and .h files from Classes to the project

UWP

  • Add all .lib files under proj.win10/[WIN10_PROJECT_NAME]/libs as linker input under additional dependencies for both Debug and Release configurations
  • Add all .cpp and .h files from Classes to the project

Configure Tizen IDE

tizen-manifest.xml

Add the following privileges to the manifest file:

Tizen

  • Add proj.tizen/libs as library path under “path and symbols” (found under C/C++ General)
  • Add all .a files under proj.tizen/libs as libraires under “path and symbols” (found under C/C++ General) for both Emulator, Debug and Release configurations
  • Add all .cpp and .h files from Classes to the project

Configure Linux

CMakeLists.txt

Link to dl library (as well as the other dependencies for GameAnalytics as shown in the example) for Linux build:


INITIALIZE SDK

Using the SDK

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 inside the applicationDidFinishLaunching method of the Cocos2D class AppDelegate (AppDelegate.cpp).

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

C++

Remember to import the GameAnalytics header file whenever you need to call the SDK.

JS

Nothing you need to include whenever you need to call the SDK from JavaScript.

Lua

Remember to add this line to the lua scripts whenever you need to call the SDK.


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 [major].[minor].[patch]

  • C++: gameanalytics::cocos2d::GameAnalytics::configureBuild(“android 1.0.0”);
  • JS: ga.GameAnalytics.configureBuild(“android 1.0.0”);
  • Lua: ga.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.

 

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.

  • C++: gameanalytics::cocos2d::GameAnalytics::configureUserId(“user1234567879”);
  • JS: ga.GameAnalytics.configureUserId(“user1234567879”);
  • Lua: ga.configureUserId(“user1234567879”)

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.

 

:information_source:
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.

 

C++

JS

Lua

 

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

Initialising

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

  • C++: gameanalytics::cocos2d::GameAnalytics::initialize(“[game key]”, “[secret key]”);
  • JS: ga.GameAnalytics.initialize(“[game key]”, “[secret key]”);
  • Lua: ga.GameAnalytics:initialize(“[game key]”, “[secret key]”)

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

 

C++

Below is a common example of the code placed in the AppDelegate class.

JS

Below is a common example of the code placed in main.js.

Lua

Below is a common example of the code placed in MyApp.lua.

Specific for Windows and Mac builds

When running on Windows and Mac platforms Cocos2D has no way to catch when the application exits, so to trigger the end session event add the AppDelegate.applicationDidEnterBackground() to main.cpp like this:

and add gameanalytics::GameAnalytics::onStop() to applicationDidEnterBackground() in AppDelegate.cpp like this:


ADDING EVENTS

About

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.

 

:warning:
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]:[weapon_used]:[damage_done]

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.

 

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

Business

Business events are used to track (and validate) real-money transactions.

 

:information_source:
Many games are 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.

 

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

Getting receipts in Cocos2D

To get receipts from In-App purchases in Android and iOS please look this integration guide and especially look here as you need the IAP receipts to send with your business events.

Android

Business event with receipt

When submitting a Business Event supply the following from the IAP procedure.

  • receipt (INAPP_PURCHASE_DATA)
  • signature (INAPP_DATA_SIGNATURE)

Read more about retrieving these needed fields at the Google documentation here.

 

Add a business event when an in-app purchase is completed (Google Play Store only supported at the moment).

  • C++: gameanalytics::cocos2d::GameAnalytics::addBusinessEvent(“USD”, 1000, “item”, “id”, “cart”, “[receipt]”, “[signature]”);
  • JS: ga.GameAnalytics.addBusinessEvent(“USD”, 1000, “item”, “id”, “cart”, “[receipt]”, “[signature]”);
  • Lua: ga.GameAnalytics:addBusinessEvent(“USD”, 1000, “item”, “id”, “cart”, “[receipt]”, “[signature]”)

 

Field Type Description Example
currency string Currency code in ISO 4217 format. USD
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.
EndOfLevel
receipt string The transaction receipt. Null allowed. null
signature base64 string The transaction receipt signature. Null allowed. null

 

If the receipt/signature is null (or is an invalid receipt) then it will be submitted to the GA server but will register as not validated.

Android receipt json schema

The encoding of the receipt will be done by the GameAnalytics native Android library.

iOS

Business event with receipt

When an in-app purchase is completed call the following method.

  • C++: gameanalytics::cocos2d::GameAnalytics::addBusinessEvent(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”, “[receipt]”);
  • JS: ga.GameAnalytics.addBusinessEvent(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”, “[receipt]”);
  • Lua: ga.GameAnalytics:addBusinessEvent(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”, “[receipt]”)

 

Field Type Description Example
currency string Currency code in ISO 4217 format.
http://openexchangerates.org/currencies.json
USD
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.
EndOfLevel
receipt base64 string The transaction receipt. Null allowed. null

 

If the receipt is null (or is an invalid receipt) then the GA servers will register that amount as not validated.

 

Business event with auto fetch receipt (iOS7+)

Using an alternative method it is possible to let the SDK retrieve the receipt automatically when called directly after a successful in-app purchase. The code performed by the SDK is identical (almost) to the objective-c example above for iOS7+.

:warning:
Using this method on iOS6.x devices will cause the business event to be ignored. When supporting iOS6 you should retrieve and specify receipt manually.

  • C++: gameanalytics::cocos2d::GameAnalytics::addBusinessEventAndAutoFetchReceipt(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”);
  • JS: ga.GameAnalytics.addBusinessEventAndAutoFetchReceipt(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”);
  • Lua: ga.GameAnalytics:addBusinessEventAndAutoFetchReceipt(“USD”, 999, “Weapon”, “SwordOfFire”, “Menu”)

How to get receipts using SDKBOX IAP (Android and iOS)

It is assumed that you have already set up and configured SDKBOX IAP correctly, if not please go here for more information on how to do this.

Make sure you have called these methods before making In-App purchases (where iapListener implements public sdkbox::IAPListener):

Here is how to get receipts and to use to send business events so they get marked as valid events:

So on Android receiptCipheredPayload contains the signature needed for the business events and iOS receiptCipheredPayload is the receipt.

 

:information_source:
For more information regarding business events go here.

Resource

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.

:information_source:
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.

  • C++: gameanalytics::cocos2d::GameAnalytics::addResourceEvent(gameanalytics::cocos2d::EGAResourceFlowType::Source, “Gems”, 400, “IAP”, “Coins400”);
  • JS: ga.GameAnalytics.addResourceEvent(ga.EGAResourceFlowType.Source, “Gems”, 400, “IAP”, “Coins400”);
  • Lua: ga.GameAnalytics:addResourceEvent(ga.EGAResourceFlowType.Source, “Gems”, 400, “IAP”, “Coins400”)

sink (subtract) Gem currency to buy an item.

  • C++: gameanalytics::cocos2d::GameAnalytics::addResourceEvent(gameanalytics::cocos2d::EGAResourceFlowType::Source, “Gems”, 400, “IAP”, “Coins400”);
  • JS: ga.GameAnalytics.addResourceEvent(ga.EGAResourceFlowType.Source, “Gems”, 400, “IAP”, “Coins400”);
  • Lua: ga.GameAnalytics:addResourceEvent(ga.EGAResourceFlowType.Source, “Gems”, 400, “IAP”, “Coins400”)

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

C++

JS

Lua

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

  • C++: gameanalytics::cocos2d::GameAnalytics::addResourceEvent(gameanalytics::cocos2d::EGAResourceFlowType::Sink, “BeamBooster”, 3, “Gameplay”, “BeamBooster5Pack”);
  • JS: ga.GameAnalytics.addResourceEvent(ga.EGAResourceFlowType.Sink, “BeamBooster”, 3, “Gameplay”, “BeamBooster5Pack”);
  • Lua: ga.GameAnalytics:addResourceEvent(ga.EGAResourceFlowType.Sink, “BeamBooster”, 3, “Gameplay”, “BeamBooster5Pack”)

 

Field Type Description Example
flowType enum A defined enum for sourcing and sinking resources. gameanalytics::EGAResourceFlowType::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

 

:warning:
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.

 

:information_source:
For more information on the resource event go here.

Progression

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.

  • C++: gameanalytics::cocos2d::GameAnalytics::addProgressionEvent(gameanalytics::cocos2d::EGAProgressionStatus::Start, “world01”, “stage01”, “level01”);
  • JS: ga.GameAnalytics.addProgressionEvent(ga.EGAProgressionStatus.Start, “world01”, “stage01”, “level01”);
  • Lua: ga.GameAnalytics:addProgressionEvent(ga.EGAProgressionStatus.Start, “world01”, “stage01”, “level01”)

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 gameanalytics::cocos2d::EGAProgressionStatus::Start gameanalytics::cocos2d::EGAProgressionStatus::Fail gameanalytics::cocos2d::EGAProgressionStatus::Complete
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 completes or fails a progression attempt. 1023

 

:information_source:
For more information on the progression event go here.

Error

Error Events

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:

  • C++: gameanalytics::cocos2d::GameAnalytics::addErrorEvent(gameanalytics::cocos2d::EGAErrorSeverity::Debug, “Something went bad in some of the smelly code!”);
  • JS: ga.GameAnalytics.addErrorEvent(ga.EGAErrorSeverity.Debug, “Something went bad in some of the smelly code!”);
  • Lua: ga.GameAnalytics:addErrorEvent(ga.EGAErrorSeverity.Debug, “Something went bad in some of the smelly code!”)

 

Field Type Description Example
severity enum Severity of error gameanalytics::cocos2d::EGAErrorSeverity::Debug
gameanalytics::cocos2d::EGAErrorSeverity::Info
gameanalytics::cocos2d::EGAErrorSeverity::Warning
gameanalytics::cocos2d::EGAErrorSeverity::Error
gameanalytics::cocos2d::EGAErrorSeverity::Critical
message string Error message (can be null) “Error when entering level12”

 

:information_source:
For more information on the error event go here.

Design

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.

:information_source:
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.

  • C++: gameanalytics::cocos2d::GameAnalytics::addDesignEvent(“Kill:Sword:Robot”);
  • JS: ga.GameAnalytics.addDesignEvent(“Kill:Sword:Robot”);
  • Lua: ga.GameAnalytics:addDesignEvent(“Kill:Sword:Robot”)

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

 

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

A bad implementation example.
[level_name]:[weapon_used]:[damage_done]

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.

 

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

CUSTOM DIMENSIONS

Using Custom Dimensions

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 these event categories.

  • Business
  • Resource
  • Progression

Setting each custom dimension.

C++

JS

Lua

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

 

:information_source:
Read more about custom dimensions here.

DEMOGRAPHICS

User Information

During the game it is possible to set information about your users that will then be annotated to all other events.

  • gender
  • Facebook ID
  • birthyear (age)

:information_source:
These user values will persist cross session/game-launch.
Set them to nil to reset.

 

Set gender.

  • C++: gameanalytics::cocos2d::GameAnalytics::setGender(gameanalytics::cocos2d::EGAGender::Female);
  • JS: ga.GameAnalytics.setGender(ga.EGAGender.Female);
  • Lua: ga.GameAnalytics:setGender(ga.EGAGender.Female)

Set birthyear.

  • C++: gameanalytics::cocos2d::GameAnalytics::setBirthYear(1980);
  • JS: ga.GameAnalytics.setBirthYear(1980);
  • Lua: ga.GameAnalytics:setBirthYear(1980)

Set Facebook ID.

  • C++: gameanalytics::cocos2d::GameAnalytics:setFacebookId(“123456789012345”);
  • JS: ga.GameAnalytics.setFacebookId(“123456789012345”);
  • Lua: ga.GameAnalytics:setFacebookId(“123456789012345”)

 

Field Type Description Example
gender string Gender of player. gameanalytics::cocos2d::EGAGender::Female, gameanalytics::cocos2d::EGAGender::Male
birthYear integer The year the player was born. 1980
facebookId string Facebook Id of the player. 123456789012345

DEBUG & VERIFY

Debugging

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 – remember to turn it off in production!

  • C++: gameanalytics::cocos2d::GameAnalytics::setEnabledInfoLog(true);
  • JS: ga.GameAnalytics.setEnabledInfoLog(true);
  • Lua: ga.GameAnalytics:setEnabledInfoLog(true)

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.

  • C++: gameanalytics::cocos2d::GameAnalytics::setEnabledVerboseLog(true);
  • JS: ga.GameAnalytics.setEnabledVerboseLog(true);
  • Lua: ga.setEnabledVerboseLog(true)

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.

Troubleshooting example.

C++

JS

Lua


Verify Implementation

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.

 

:information_source:
Read more about the realtime dashboard and our data processing.

HOW DOES IT WORK?

Session Handling

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

On Android a new session will start once the game is launched (or when the app is “resuming”). A session will end once the game is going to homescreen (or is not visible anymore).

On iOS a new session will start once the game is launched (or when the app is “going to foreground”). A session will end once the game is “going to background”.

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

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

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.

C++

JS

Lua

The configureBuild is required to be called before initialize is completely finished. The design event call is required after initialize is finished. The queuing will make sure that each task is completely finished before proceeding to the next one.

There is more!

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!