Skip to main content

Setup

The Defold SDK includes platform support for iOS, Android, HTML5, Windows, Linux and Mac.

Requirements​

  • Defold: 1.2.108+
  • iOS: iOS 7+
  • Android: Android API Level 14

Build size​

The SDK contain support for all platforms and CPU architectures. Note that 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.

Installation​

Github Repository​

To install the SDK add these links to the project dependencies (this will always get the latest version):

Or to get a specific version use a link like this (this example will get version 1.0.0): https://github.com/GameAnalytics/GA-SDK-DEFOLD/archive/1.0.0.zip

Configuring game.project​

The game.project file must configured before using the SDK. The available configuration options are listed here.

  • Game Key + Secret Key
  • Build (optional)
  • Custom dimensions (optional)
  • Resource Currency and Item Types (optional)
  • Use custom user id (optional)
  • Use manual session handling (optional)
  • Logging
  • Enable/disable event submission
  • Enable/disable error reporting
  • Writable path (only desktop platforms)

Remember to create new section for the SDK in the game.project file:

[gameanalytics]

Game Key + Secret Key

For each platform you need to configure a set of game keys:

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

Notice there is a specific entry for each platform:

[gameanalytics]
game_key_ios = IOS_GAME_KEY
secret_key_ios = IOS_SECRET_KEY
game_key_android = ANDROID_GAME_KEY
secret_key_android = ANDROID_SECRET_KEY
game_key_html5 = HTML5_GAME_KEY
secret_key_html5 = HTML5_SECRET_KEY
game_key_osx = OSX_GAME_KEY
secret_key_osx = OSX_SECRET_KEY
game_key_windows = WINDOWS_GAME_KEY
secret_key_windows = WINDOWS_SECRET_KEY
game_key_linux = LINUX_GAME_KEY
secret_key_linux = LINUX_SECRET_KEY

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:

[gameanalytics]
build_ios = 0.1
build_android = 0.1
build_html5 = 0.1
build_osx = 0.1
build_windows = 0.1
build_linux = 0.1

Auto detect app version to use for build field​

There is an option to auto detect app version to use for build field but it is only supported for Android and iOS platforms. The feature is enabled like this:

[gameanalytics]
auto_detect_app_version = 1

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

tip

For more information about Custom Dimensions go here.

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

[gameanalytics]
custom_dimensions_01 = ninja,samurai
custom_dimensions_02 = whale,dolphin
custom_dimensions_03 = horde,alliance

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.

tip

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

[gameanalytics] resource_currencies = gold,gems resource_item_types = boost,lives

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.

tip

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.

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.

To enable custom user id, add this to the game.project file:

[gameanalytics]
use_custom_id = 1

To set custom user id in the game call this from your script:

gameanalytics.configureUserId( "my_custom_id" )

Use manual session handling​

To enable manual session handling, add this to the game.project file:

[gameanalytics]
use_manual_session_handling = 1

To manual enable or disable session handling later on call this:

gameanalytics.setEnabledManualSessionHandling(true)
tip

Read more about sessions here including manual session handling.

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.

To enable them add this to the game.project file:

[gameanalytics]
enable_info_log = 1
enable_verbose_log = 1

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.

If you want to enable/disable event submission from the game.project file then add this to the game.project file:

[gameanalytics]
enable_event_submission = 1

Enable/disable error reporting​

This is disabled by default to not overwrite Defold error reporting. If you want to enable it do like this in the game.project file:

[gameanalytics]
enable_error_reporting = 1

Writable path (only desktop platforms)​

You can change default writable path for the SDK (but only for Mac, Linux and Windows). To do this you add this to the game.project file:

[gameanalytics]
write_path_osx = $HOME/test/test1/test2
write_path_windows = %USERPROFILE%/test/test1/test2
write_path_linux = $HOME/test/test1/test2

As you can see from the example you can use environment variables inside the desired writable path. Any missing directories in the path will also be created.

For HTML5 builds you need to manually add this line to the resulting .html file:

<script type="text/javascript" src="GameAnalytics.js"></script>

It is also possible to create a html template file where it is already added to.

Add permission​

Add the following permission, if it is not already present in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.READ_PHONE_STATE" />
tip

Remember that after Android 6.0 it might be necessary to request app permission if the Android OS has not already been altered to avoid it.

Use the plugin​

Finally, in order to read IMEI and MEID values, you need to call add the following line under the gameanalytics section to you game.project file:

[gameanalytics]
use_imei_android = 1

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.

tip

Read more about configuration here.

Initialize call will start the SDK and activate the first session. The SDK is automatically intialized when the Defold GameAnalytics extension is loaded. It uses the keys set in the game.project file.

Once the project dependency has been added the SDK should be ready use from any lua script in the project.