Skip to main content

Setup

In this integration guide we will take you through the initial steps of instrumenting your game with the GameAnalytics Flutter SDK.

Download and Installation​

To install the Flutter SDK you need to write run the command from your Flutter project direcotry in your terminal: flutter pub add gameanalytics_sdk

Or you can add the following to your pubspec.yaml (and run flutter pub get after in the terminal):

dependencies:
  gameanalytics_sdk: ^1.0.6

Web​

If you are building for web then remember to add the following line to the head of the index.html:

<head>
  <!-- other code -->
  <script src="http://download.gameanalytics.com/js/GameAnalytics-{VERSION}.min.js"></script>
  <!-- other code -->
</head>

Replace VERSION with the desired version of GameAnalytics JavaScript SDK library. Find the latest version number here.

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.

Remember to import the GameAnalytics package whenever you need to call the SDK:

import 'package:gameanalytics_sdk/gameanalytics.dart';

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

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

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.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. A maximum of 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"]);

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.

Initialize Call​

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

GameAnalytics.initialize("[game key]", "[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.

void initState() {
    super.initState();

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

    GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
    GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
    GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);
    GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"]);
    GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);
    GameAnalytics.configureBuild("0.1.0");
    GameAnalytics.initialize("[game key]", "[secret key]");
}