Skip to main content

Getting Started with GameAnalytics Flutter SDK

This guide explains how to integrate the GameAnalytics SDK into your Flutter project.

tip

Stay updated with the latest changes by checking the GameAnalytics Flutter SDK Changelog.

1. Install the SDK​

1.1. Installation via Command Line​

To install the Flutter SDK, run the following command from your Flutter project directory in your terminal:

flutter pub add gameanalytics_sdk

1.2. Manual Installation​

Alternatively, you can manually add the dependency to your pubspec.yaml file:

dependencies:
  gameanalytics_sdk: ^1.3.0

After adding the dependency, run the following command in your terminal:

flutter pub get

1.3. Configuration for Web​

If you're building for the web, add the following script tag to the <head> section of your index.html file:

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

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

2. SDK Integration​

2.1. Import the SDK​

Before using the GameAnalytics SDK, import the package in your Dart files:

import 'package:gameanalytics_sdk/gameanalytics.dart';

2.2. Create Account​

info

If you don't have an account yet, head over here and register your game on the GameAnalytics website!

After you've set up your organization, studio, and game, you will be able to find your game's keys in the Game Settings section of the web tool.

2.3. SDK Lifecycle​

The GameAnalytics SDK follows a 3-phase lifecycle:

  1. Configuration – Configure settings for the SDK before initialization
  2. Initialization – Start the SDK and activate the first session
  3. Event Tracking – Add events and update dimensions throughout your game
caution

Some configuration calls cannot be altered after initialization has been called. Always configure the SDK before calling initialize().

The configuration and initialization steps should be called when your application starts.

3. Configuration​

The configuration phase happens before initialization is called. Configure the SDK by calling the appropriate methods as described below.

3.1. Set Build Version​

The build version is used to specify the current version of your game. Use a string value, preferably following a 3-part version format like [major].[minor].[patch].

GameAnalytics.configureBuild("0.1.1");

Auto-detect App Version​

You can enable automatic detection of the app version to use for the build field. Call this before initializing the SDK:

GameAnalytics.configureAutoDetectAppVersion(true);

3.2. Configure Custom User ID​

The SDK will automatically generate a user ID, which is perfectly fine for almost all cases.

Sometimes it's useful to provide the user_id manually – for example, if you download raw data for processing and need to match your internal user ID (for example, a database index in your user table) to the data collected through GameAnalytics.

caution

Do not use a custom user ID unless you have a specific need for 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's lifetime.

GameAnalytics.configureUserId("my_user_id");

3.3. Configure Available Custom Dimensions​

For custom dimensions, you must define a whitelist of the unique values you plan to use during the configuration phase. After initialization, only the specified values are allowed. A maximum of 20 values is 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 help guide users in planning which dimension values to use.

GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);

3.4. Configure Available Resources​

Define the available resource currencies and item types that your game will track:

GameAnalytics.configureAvailableResourceCurrencies(["gold", "gems"]);
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);
info

Each resource currency string should only contain [A-Za-z] characters.

3.5. Enable/Disable Event Submission​

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

GameAnalytics.setEnabledEventSubmission(false);

By default, event submission is enabled. You will still receive configuration updates if you have set any for your game, even after disabling event submission.

4. Initialize the SDK​

4.1. Initialize Call​

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

GameAnalytics.initialize("[game key]", "[secret key]");
tip

Replace [game key] and [secret key] with your actual keys from the GameAnalytics web tool.

4.2. Complete Initialization Example​

Below is a common example of initialization code that you can place in your widget's initState() method:

void initState() {
  super.initState();

  // Enable logging for debugging purposes
  GameAnalytics.setEnabledInfoLog(true);
  GameAnalytics.setEnabledVerboseLog(true);

  // Configure custom dimensions
  GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
  GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
  GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);

  // Configure resources
  GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"]);
  GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);

  // Set build version
  GameAnalytics.configureBuild("0.1.0");

  // Initialize the SDK
  GameAnalytics.initialize("[game key]", "[secret key]");
}

5. Start Tracking Events​

Once the SDK is initialized, you can start tracking events throughout your game.

The GameAnalytics SDK supports 5 different types of events: Business, Resource, Progression, Error and Design.

Learn more about what each event type does and how to use them on the Event Tracking page.

info

Remember to call event tracking methods only after the SDK has been initialized.