Skip to main content

Setup

The Cocos2D SDK include platform support for:

  • iOS
  • Android
  • HTML5
  • Tizen
  • Windows
  • Linux
  • UWP
  • MacOS

Engine languages supported:

  • C++
  • JavaScript
  • Lua
tip

From v1.8.0 and onwards the jsbindings have been updated to work with the latest API, if you need to use jsbindings for the previous API please get the jsbindings from v1.7.7.

Installation​

You can download the SDK from the github repo.

C++ installation​

Copy the following 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

JavaScript installation​

  • Copy all the files inside the js/src folder and paste them 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.linux folder and paste it here: [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/proj.linux

Add the following line in [JS_PROJECT_ROOT_FOLDER]/project.json under the jsList section:

src / ga_enums.js;

Inside [JS_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes/AppDelegate.cpp include the following header:

#include "jsbindings/GameAnalyticsJS.hpp"

In the applicationDidFinishLaunching() method add the following line

sc->addRegisterCallback(register_all_GameAnalyticsJS);

Lua installation​

  • 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

Inside [LUA_PROJECT_ROOT_FOLDER]/frameworks/runtime-src/Classes/AppDelegate.cpp Include the following header:

#include "luabindings/GameAnalyticsLua.hpp"

Add the following line in the applicationDidFinishLaunching() method:

register_all_GameAnalyticsLua(L);

Cocos Creator Installation (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:

npm install gameanalytics

And init the SDK as shown below:

var ga = require("gameanalytics");

ga.GameAnalytics.setEnabledInfoLog(true);

IDE Configuration​

Android Studio​

Gradle​

info

Ice Cream Sandwich 4.0 (API level 14) or higher required.

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

maven { url 'https://maven.gameanalytics.com/release'; }

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

compileSdkVersion 24
buildToolsVersion "24.0.2"
targetSdkVersion 24

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

// use latest version instead version number in this example
compile 'com.gameanalytics.sdk:gameanalytics-android:+'
tip

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

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

gameanalytics/GameAnalyticsJNI.cpp
../../../Classes/GameAnalytics.cpp

Also add the following to the LOCAL_C_INCLUDES section.

$(LOCAL_PATH)/gameanalytics

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:

android:configChanges="orientation|screenSize|keyboardHidden"

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

<activity
    android:name=".MainActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:label="@string/app_name" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
</activity>

Xcode​

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

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

MacOS 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

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

Tizen IDE​

  • 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 libraries 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

CMake (for linux)​

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

if(LINUX)
    target_link_libraries(${APP_NAME}
        ${PROJECT_SOURCE_DIR}/proj.linux/libs/libcrypto.a
        ${PROJECT_SOURCE_DIR}/proj.linux/libs/libcurl.a
        ${PROJECT_SOURCE_DIR}/proj.linux/libs/libGameAnalytics.a
        ${PROJECT_SOURCE_DIR}/proj.linux/libs/libssl.a
        dl
    )
endif(LINUX)

Initialization​

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

#include "GameAnalytics.h"

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");

Auto detect app version​

There is also an option to auto detect app version in order to use it for build field instead of manually introducing the build number. You can do so by calling the following method before initialization:

// C++
gameanalytics::cocos2d::GameAnalytics::configureAutoDetectAppVersion(true);

Custom User 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.

caution

Prefer to not use a custom userId unless you have a specific need for it.

note

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's lifetime.

// C++
gameanalytics::cocos2d::GameAnalytics::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.

caution

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.

    gameanalytics::cocos2d::GameAnalytics::configureAvailableResourceCurrencies({"gems", "gold"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableResourceItemTypes({"boost", "lives"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions01({"ninja", "samurai"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions02({"whale", "dolphin"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions03({"horde", "alliance"});

Control Event Submission​

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

// C++
gameanalytics::cocos2d::GameAnalytics::setEnabledEventSubmission(false);

Initializing​

After configuration you need to initialize the SDK with the following method:

// C++
gameanalytics::cocos2d::GameAnalytics::initialize("[game key]", "[secret key]");
tip

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

Sessions​

Once initialize is called it will start the first session. On mobile platforms and UWP platform the SDK will automatically handle session changes when the application goes to the background.

Below you can find an example of how to initialize a session:

#include "GameAnalytics.h"

bool AppDelegate::applicationDidFinishLaunching() {
    // ... other code from your project ...

    gameanalytics::cocos2d::GameAnalytics::setEnabledInfoLog(true);
    gameanalytics::cocos2d::GameAnalytics::setEnabledVerboseLog(true);

    gameanalytics::cocos2d::GameAnalytics::configureBuild("0.10");

    gameanalytics::cocos2d::GameAnalytics::configureAvailableResourceCurrencies({"gems", "gold"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableResourceItemTypes({"boost", "lives"});

    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions01({"ninja", "samurai"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions02({"whale", "dolphin"});
    gameanalytics::cocos2d::GameAnalytics::configureAvailableCustomDimensions03({"horde", "alliance"});

    gameanalytics::cocos2d::GameAnalytics::initialize("[game key]", "[secret key]");

    return true;
}

For Windows & MacOS​

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:

int main(int argc, char *argv[])
{
    AppDelegate app;
    int i = Application::getInstance()->run();
    app.applicationDidEnterBackground();
    return i;
}

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

// ...other headers
#if (CC_TARGET_PLATFORM == CC_PLATFORM_MAC) || (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
#include "cpp/GameAnalytics.h"
#endif

// ...other code

void AppDelegate::applicationDidEnterBackground() {
    // ...other code

#if (CC_TARGET_PLATFORM == CC_PLATFORM_MAC) || (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
    gameanalytics::GameAnalytics::onQuit();
#endif
}
FieldTypeDescriptionExample
currencystringCurrency code in ISO 4217 format.USD
amountintegerAmount in cents.99 is 0.99$
itemTypestringThe type / category of the item.GoldPacks
itemIdstringSpecific item bought.1000GoldPack
cartTypestringThe game location of the purchase. Max 10 unique values.EndOfLevel
receiptbase64 stringThe transaction receipt. Null allowed.null
signaturebase64 stringThe transaction receipt signature. Null allowed.null
caution

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.