Setup

The Godot SDK includes platform support for:

• iOS
• Android
• Web
• Windows
• MacOS
• Linux.

Requirements

• Godot: 4.0+
• iOS: iOS 7+
• Android: Android API Level 14

Installation

Download the SDK from the Github Repository and unzip the file.

You can also install the plugin using NativeLib addon to go here for how to install it.

Android

To use this module you’ll need a custom template for Android which you need to build yourself. Another option available is to use the new Android plugin system for Godot 3.2.2 or higher which is much easier to use (no recompilation needed). This module is located under the android_godot_3_2 folder.

Using new Android plugin system (Godot 3.2.2 or higher)

• Open your project in Godot
• Install Export Templates if necessary
• Install Android build template
• Copy both GameAnalytics.gdap and GameAnalytics.release.aar found under android_godot_3_2/downloads
• In Godot select menu Project > Export, add Android and edit your settings (package unique name, keystores, etc.) and select under Custom Template: Use Custom Build and also under Plugins: GameAnalytics.

Without the new Android plugin system

• Clone or download the Godot Engine repository. One important note here is that this must match the same version of the Godot editor you’re using to develop your game.
• Drop the gameanalytics directory inside the modules directory on the Godot source.
• Recompile the android export template following the official instructions.

To enable the module on Android, add the path to the module to the “modules” property on the [android] section of your project.godot. It should look like this:

[android]
modules="org/godotengine/godot/GodotAdMob"

iOS

• Drop the gameanalytics directory inside the modules directory on the Godot source.
• Recompile the iOS export template.

Web

• Drop the gameanalytics directory inside the modules directory on the Godot source.
• Recompile the Web export template.

Mac, Windows and Linux

• Drop the gameanalytics directory inside the modules directory on the Godot source.
• Recompile the export templates.
  • Windows
  • OSX
  • [Linux] (docs)
• When recompiling the engine is finished do the following before running it the first time:
  • Copy the shared library (GameAnalytics.dll, libGameAnalytics.dylib or libGameAnalytics.so depending on the OS) from the Libraries-folders to the Godot binary location (by default in the godot source /bin/ file but you can move them to a new folder).
  • Your game must ship with the executable and the the shared library to function. Lack of the DLL/SO/DyLib (for your respective OS) will cause it to fail and crash.

info

NOTE: For OSX, the libGameAnalytics.dylib must be in the Content/MacOS/ folder in your application zip or the game will crash.

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 when the application starts.

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

To access the GameAnalytics object, do this:

var GameAnalytics
# other code...
if(Engine.has_singleton("GameAnalytics")):
    GameAnalytics = Engine.get_singleton("GameAnalytics")

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]

GameAnalytics.configureBuild("0.1.1");

tip

You can auto detect app version to use for build field (only Android and iOS)

There is an option to auto detect app version to use for build field. Just call this before intializing the SDK:

GameAnalytics.configureAutoDetectAppVersion(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.

info

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.configureUserId("my_user_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.

danger

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.configureAvailableCustomDimensions01(["ninja", "samurai"]);
GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);
GameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"]);
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);

info

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.initialize({
    gameKey: [game key]",
    secretKey: "[secret key]
});

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

var GameAnalytics
func _ready(){
    # ... other code from your project ...
    if(Engine.has_singleton("GameAnalytics")):
        GameAnalytics = Engine.get_singleton("GameAnalytics")
        GameAnalytics.setEnabledInfoLog(true)
        GameAnalytics.setEnabledVerboseLog(true)

        GameAnalytics.configureBuild("0.1.1")

        GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"])
        GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"])
        GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"])
        GameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"])
        GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"])

        GameAnalytics.init([game key], [secret key])
}