Skip to main content

Setup

Download​

Unzip the downloaded .zip and place the .ane file inside your project’s extensions folder. Additions to AIR descriptor

Add the extension’s ID to the extensions element.

    com.gameanalytics.sdk

Size considerations​

The GameAnalytics .ane file is around 40MB. The size of your app will not increase by 40MB.

The .ane file include architectures for many platforms (Android, iOS, Windows and Mac) and during compiling only the necessary architecture for the target platform will be used. Size example

A simple Hello World iOS app is 7.40MB built with the AIR SDK (without GameAnalytics). When adding GameAnalytics the size is 7.57MB.

The addition is 157KB and the same behaviour is relevant on other platforms supported.

Configuration for Android​

AIR descriptor file​

manifestAdditions​

Modify the manifestAdditions so that it contains the following permissions and meta data:

<android>
    <manifestAdditions>
        <![CDATA[
        <manifest android:installLocation="auto">
            <uses-permission android:name="android.permission.INTERNET" />
            <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

            <uses-sdk android:targetSdkVersion="23" />

            <application>

                <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

            </application>

        </manifest>
        ]]>
    </manifestAdditions>
</android>

The Google Play Services ANEs are only necessary during packaging.

note

Including this and other extensions in your app increases the number of method references that must be stored in Android dex file. AIR currently supports a single dex file and since the number of such references is limited to a little over 65k, it is possible to exceed the limit by including several native extensions. This will prohibit you from building your app for Android, unless you reduce the number of features the app provides. Please, leave a vote in the report below to help adding multidex support to AIR SDK:

Bug 4190396 – Multidex support for Adobe AIR

Configuration for IOS​

caution

Important: iOS app submission

The GA SDK for iOS uses Advertising Identifier (IDFA). Make sure to read this guide when submitting the app to the App Store to avoid rejection.

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

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 at the beginning of the game for example inside the GameInit method.

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 import the GameAnalytics package whenever you need to call the SDK.

import com.gameanalytics.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]

// Set build version for iOS, Android, Mac and Windows
GameAnalytics.config
    .setBuildAndroid("0.1.0")
    .setBuildiOS("0.1.0")
    .setBuildMac("0.1.0")
    .setBuildWindows("0.1.0");

Auto detect app version to use for build field​

There is an option to auto detect app version to use for build field (only works for iOS and Android). Just call this before intializing the SDK:

GameAnalytics.config
    .setAutoDetectAppVersion(true);

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.

GameAnalytics.config
    .setUserId("test_id");

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

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.

GameAnalytics.config
    .setResourceCurrencies(new <String>["gems", "coins"])
    .setResourceItemTypes(new <String>["boost", "lives"])
    .setCustomDimensions01(new <String>[ "ninja", "samurai" ])
    .setCustomDimensions02(new <String>[ "whale", "dolphin" ])
    .setCustomDimensions03(new <String>["horde", "alliance"]);
tip

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.setEnabledEventSubmission(false);

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​

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

GameAnalytics.config
    .setGameKeyAndroid("[android_game_key]")
    .setGameSecretAndroid("[android_secret_key]")
    .setGameKeyiOS("[ios_game_key]")
    .setGameSecretiOS("[ios_secret_key]")
    .setGameKeyMac("[mac_game_key]")
    .setGameSecretMac("[mac_secret_key]")
    .setGameKeyWindows("[windows_game_key]")
    .setGameSecretWindows("[windows_secret_key]");

// Initialize
if(GameAnalytics.init())
{
    // SDK has been initialized correctly now
}
tip

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

Below is a common example of the code placed in the GameInit method.

import com.gameanalytics.sdk.*;

package my.package
{
    public class MyClass
    {
        public function MyClass()
        {
            // ... other code from your project ...

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

            GameAnalytics.config
                .setBuildAndroid("0.1.0")
                .setBuildiOS("0.1.0")
                .setBuildMac("0.1.0")
                .setBuildWindows("0.1.0")
                .setResourceCurrencies(new <String>["gems", "coins"])
                .setResourceItemTypes(new <String>["boost", "lives"])
                .setCustomDimensions01(new <String>["ninja", "samurai"])
                .setCustomDimensions02(new <String>["whale", "dolphin"])
                .setCustomDimensions03(new <String>["horde", "alliance"])
                .setGameKeyAndroid("[android_game_key]")
                .setGameSecretAndroid("[android_secret_key]")
                .setGameKeyiOS("[ios_game_key]")
                .setGameSecretiOS("[ios_secret_key]")
                .setGameKeyMac("[mac_game_key]")
                .setGameSecretMac("[mac_secret_key]")
                .setGameKeyWindows("[windows_game_key]")
                .setGameSecretWindows("[windows_secret_key]");

            if(GameAnalytics.init())
            {
                // SDK has been initialized now and you can send events now
            }
    }
}