GameAnalytics

Introduction

---

GameAnalytics is a leading analytics and data management platform designed to help game developers monitor and optimize the performance of their games.

Make use of Plankton to leverage the capabilities of GameAnalytics in your project.

Before you begin

---

Prerequisites

• Complete the Plankton setup

Set up your account

1. Register for a Game Analytics account and create your game in it.
2. Retrieve the game key and secret key of your game. It is needed further in this guide.

Confiure Plankton settings

---

1. Open plankton settings by going to Edit > Project Settings > Plankton.
2. Select the checkbox of Game Analytics.
3. Save these settings by clicking on "Apply Changes" button.

Implementation

---

Now we should be ready for adding code to activate the SDK! Remember to import the Plankton package wherever you need to use it.

using Plankton;

Initialize

Initialization of Game Analytics in Plankton includes both configuration and initialization. You can read more about the available configuration options to understand the available options. You also need the game key and secret key that you retrieved in the previous steps.

Here's a sample that show initialization with all possible configurations:

var builder = new GameAnalytics.Builder("GAME_KEY", "SECRET_KEY")
    .SetUserId("user_id")
    .SetBuildVersion("1.0.0")
    .ConfigureResourceCurrencies("stone", "gold")
    .ConfigureItemTypes("shop")
    .ConfigureCustomDimensions01("tester", "player")
    .ConfigureCustomDimensions02("group1", "group2")
    .ConfigureCustomDimensions03("Warrior", "Archer")
    .SetInfoLogEnable(true)
    .SetVerboseLogEnable(false)

GameAnalytics.Initialize(builder, () => Debug.Log("Initialization finished!"));

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. These lists include: resourceCurrencies, resourceItemTypes, customDimensions01, customDimensions02, and customDimensions03.

danger

Processing many unique dimension values can be taxing for GameAnalytics servers. A few games with poor implementation can seriously increase their cost and affect stability. Games will be blocked if they submit too many unique dimension values. They have this configuration requirement to guide users in planning what dimension values can be used.

Custom Dimensions

GameAnalytics supports up to 3 custom dimensions. During the game it is possible to set the active value for each custom dimension dynamically. Once a dimension is set it will be persisted across sessions/game-start and automatically be added to all event categories.

GameAnalytics.SetCustomDimension01("tester");
GameAnalytics.SetCustomDimension02("group1");
GameAnalytics.SetCustomDimension03("Archer");

To reset a custom dimension simply set it to empty string or null:

GameAnalytics.SetCustomDimension01("");
GameAnalytics.SetCustomDimension02("");
GameAnalytics.SetCustomDimension03("");

Caution

Remember you have to set custom dimensions from one of the available values that you configured during the initialization.

Event tracking

GameAnalytics features several types of events. Read more about event types.

Custom event fields

For all types of events, it is possible to use a set of key-value pairs to add extra fields but it will only be available through raw data export. If you want to merge the specified custom fields from the event method parameter with the global custom event fields set the optional mergeFields parameter to true. Here is an example of how to use it:

Dictionary<string, string> fields = new Dictionary<string, object>();
fields.put("test_1", "test value 1");
fields.put("test_2", "test value 2");
var mergeFields = true;
GameAnalytics.AddBusinessEvent("USD", 999, "item", "id", "cart", fields, mergeFields);

This signature is similliar for all event methods. The last two arguments are always fields and mergeFields, and they are optional.

Business events

Business events are used to track (and validate) real-money transactions

With receipt

Add a business event when an in-app purchase is completed:

GameAnalytics.AddBusinessEventWithReceipt("USD", 999, "item", "id", "cart", "[receipt]", "google_play", "[signature]");

Without receipt

It is also possible to send business events without validation.

GameAnalytics.AddBusinessEvent("USD", 999, "item", "id", "cart");

info

For more information on Business Events go here.

Ad events

The GameAnalytics ad event needs to be called when certain ad events have been triggered.

GameAnalytics.AddAdEvent(GameAnalytics.AdAction.Show, GameAnalytics.AdType.RewardedVideo, "admob", "[AD_PLACEMENT_OR_UNIT_ID]");

info

For more information on Ad Events go here.

Impression events

Impression Events are used to track impression data from ads shown using different ad networks. Currently AdMob and AppLovin MAX are supported.

AdMob

If you are using AdMob through Plankton, you can enable automatic reporting of impression data to GameAnalytics with a single function call:

GameAnalytics.SubscribeAdMobImpressions();

This will automatically capture and send impression events to GameAnalytics each time an ad is shown.

Alternatively, if you want to manually send impression events, you can use the following method by providing the required parameters:

public static void AddImpressionAdMobEvent(
    string adUnitId, 
    string adType, 
    string currencyCode, 
    AdMobImpressionPrecision precision, 
    string networkName, 
    long revenue, 
    string adMobSdkVersion
)

AppLovin MAX

If you are using AppLovin MAX through Plankton, you can enable automatic reporting of impression data to GameAnalytics with a single function call:

GameAnalytics.SubscribeMaxImpressions();

This ensures that impression events are sent to GameAnalytics every time an ad is shown.

If you prefer to send events manually, you can use the following method:

public static void AddImpressionMaxEvent(
    string adUnitId, 
    string adType, 
    string networkName, 
    string country, 
    string placement, 
    string creativeId, 
    double revenue, 
    string appLovinSdkVersion
)

Resource events

Resource events are used to register the flow of your in-game economy (virtual currencies) – the sink (subtract) and the source (add) for each virtual currency.

GameAnalytics.AddResourceEvent(GameAnalytics.ResourceFlowType.Source, "stone", 80, "shop", "stone_pack");

GameAnalytics.AddResourceEvent(GameAnalytics.ResourceFlowType.Sink, "gold", 100, "shop", "gold_100");

Caution

Before calling the resource event it is needed to specify what discrete values can be used for currencies and item types in the initialization phase.

info

For more information on Resource Events go here.

Progression events

Progression events are used to track attempts at completing some part of a game (level, area). A defined area follows a 3 tier hierarchy structure (could be world:stage:level) to indicate what part of the game the player is trying to complete.

When a player is starting a progression attempt a Start event should be added.

When the player then finishes the attempt a Fail or Complete event should be added along with a score if needed.

This is an example of a Start event:

GameAnalytics.AddProgressionEvent(GameAnalytics.ProgressionStatus.Start, "world_1", "zone_3", "boss_2");

It is not required to use all 3 if your game does not have them. You can pass empty string for the latter tiers.

With score

It's also possible to pass a double value as score in this event. Below is an example of a progression event with a score parameter:

GameAnalytics.AddProgressionEventWithScore(GameAnalytics.ProgressionStatus.End, "world_2", "stage_5", "level_11", 20.0);

info

For more information on Progression Events go here.

Error events

Used to track custom error events in the game. You can group the events by severity level and attach a message. By default the SDK will automatically send error events for uncaught exceptions.

To add a custom error event call the following function:

GameAnalytics.AddErrorEvent(GameAnalytics.ErrorSeverity.Error, "Error message");

GameAnalytics.AddErrorEvent(GameAnalytics.ErrorSeverity.Critical, "Critical error message");

info

For more information on Error Events go here.

Design events

Every game is unique. Therefore some needed events might not be covered by other specified event types. The design event is available for you to add your own event-id hierarchy.

Here's a sample of adding a design event:

GameAnalytics.AddDesignEvent("Kill:Sword:Robot");

It is also possible to add a float value to the event. This will (in addition to count) make the mean and sum aggregation available in the GameAnalytics dashboard.

GameAnalytics.AddDesignEventWithValue("BossFights:FireLord:KillTimeUsed", 234f);

info

For more information on Design Events go here.

Game Ops

Remote Configs

GameAnalytics offers the option to setup remote configs in your dashboard that can be changed on a whim without needing to release a new version of the game. The remote configs are a custom set of key-pair values.

To manual check if Remote Configs is ready (has been populated with values) you can call this:

if (GameAnalytics.IsRemoteConfigsReady())
{
    // the remote configs is ready, add your code here
}

After you have checked if the configs have been populated you can use the following method to retrieve their values::

string value = GameAnalytics.GetRemoteConfigsValueAsString("key", "default value");

Caution

Remember the remote configs can be populated with an empty dictionary if the device is offline and there are no cached remote configs from a previous session.

A/B Testing

To access A/B Testing, first you have to set it up in your GameAnalytis dashboard. Every A/B test must have a config key that is identical to a remote config key so that its value can be retrieved using the same method as the remote configs.

string abValue = GameAnalytics.GetRemoteConfigsValueAsString("ab_config_key", "default value");

You can also retrive the testing ids with the following methods:

// A/B testing id
string abTestingId = GameAnalytics.GetABTestingId();

// A/B testing variant id
string abTestingVariantId = GameAnalytics.GetABTestingVariantId();

info

Remember that the A/B testing ids are first available when the Remote Configs are ready.

API Refrences

---

Defined Types

In this section, we will discuss the enumerated types and classes associated with this feature:

Enums

GameAnalytics.ErrorSeverity

Values	Description	Usage
Undefined	Use when error severity is not defined	GameAnalytics.ErrorSeverity.Undefined
Debug	Use for easier debugging	GameAnalytics.ErrorSeverity.Debug
Info	Used for communicating non-critical information	GameAnalytics.ErrorSeverity.Info
Warning	Use warnings for situations where Unity can recover/proceed, but users may be unaware of the side effects	GameAnalytics.ErrorSeverity.Warning
Error	Indicates a function will not complete an action, use errors for situations where Unity can not recover or proceed normally	GameAnalytics.ErrorSeverity.Error
Critical	This category is assigned for critical errors, such as ANRs.	GameAnalytics.ErrorSeverity.Critical

GameAnalytics.ProgressionStatus

Values	Description	Usage
Undefined	Undefined progression	GameAnalytics.ProgressionStatus.Undefined
Start	The user started a progression	GameAnalytics.ProgressionStatus.Start
Complete	The user successfully ended a progression	GameAnalytics.ProgressionStatus.Complete
Fail	The user failed a progression	GameAnalytics.ProgressionStatus.Fail

GameAnalytics.ResourceFlowType

Values	Description	Usage
Undefined	Undefined progression	GameAnalytics.ResourceFlowType.Undefined
Source	Use when adding a resource to a user	GameAnalytics.ResourceFlowType.Undefined
Sink	Use when removing a resource from a user	GameAnalytics.ResourceFlowType.Sink

GameAnalytics.AdAction

Values	Usage
Undefined	GameAnalytics.AdAction.Undefined
Clicked	GameAnalytics.AdAction.Clicked
Show	GameAnalytics.AdAction.Show
FailedShow	GameAnalytics.AdAction.FailedShow
RewardReceived	GameAnalytics.AdAction.RewardReceived
Request	GameAnalytics.AdAction.Request
Loaded	GameAnalytics.AdAction.Loaded

GameAnalytics.AdType

Values	Usage
Undefined	GameAnalytics.AdType.Undefined
Video	GameAnalytics.AdType.Video
RewardedVideo	GameAnalytics.AdType.RewardedVideo
Playable	GameAnalytics.AdType.Playable
Interstitial	GameAnalytics.AdType.Interstitial
OfferWall	GameAnalytics.AdType.OfferWall
Banner	GameAnalytics.AdType.Banner
AppOpen	GameAnalytics.AdType.AppOpen

GameAnalytics.AdError

Values	Usage
Undefined	GameAnalytics.AdError.Undefined
Unknown	GameAnalytics.AdError.Unknown
Offline	GameAnalytics.AdError.Offline
NoFill	GameAnalytics.AdError.NoFill
InternalError	GameAnalytics.AdError.InternalError
InvalidRequest	GameAnalytics.AdError.InvalidRequest
UnableToPrecache	GameAnalytics.AdError.UnableToPrecache

Classes

GameAnalytics.Builder

Field Name	Field Type	Default Value	Field Description
gameKey	string	(Required field)	The game key is the unique identifier for the game.
secretKey	string	(Required field)	The secret key is used to protect the events from being altered as they travel to GameAnalytics servers.
userId	string	string.Empty	A unique identifier of the user. This is used to detect if the user should be enrolled for A/B testing
buildVersion	string	string.Empty	It is used to specify the current version of your game. Specify it using a string. It is recommended to use a 3-digit version like [major].[minor].[patch].
resourceCurrencies	List<string>	Empty list	Specify available virtual currencies in your game. Each resource currency string should only contain [A-Za-z] characters.
resourceItemTypes	List<string>	Empty list	Specify available virtual item types
customDimensions01	List<string>	Empty list	Configure available custom dimensions
customDimensions02	List<string>	Empty list
customDimensions03	List<string>	Empty list
infoLog	bool	true	Enable logs
verboseLog	bool	false

Method Summaries

Method	Arguments	Return Type
Initialize	GameAnalytics.Builder builder, System.Action callback	void
SetCustomDimension01	string value	void
SetCustomDimension02	string value	void
SetCustomDimension03	string value	void
AddBusinessEvent	string currency,int amount,string itemType,string itemId,string cartType, Dictionary<string, string> fields = null,bool mergeFields = false	void
AddBusinessEventWithReceipt	string currency,int amount,string itemType,string itemId,string cartType,string receipt,string store,string signature, Dictionary<string, string> fields = null,bool mergeFields = false	void
AddResourceEvent	ResourceFlowType flowType, string currency,float amount,string itemType,string itemId, Dictionary<string, string> fields = null,bool mergeFields = false	void
AddProgressionEvent	ProgressionStatus progressionStatus,string progression01,string progression02,string progression03,Dictionary<string, string> fields = null,bool mergeFields = false	void
AddProgressionEventWithScore	ProgressionStatus progressionStatus,string progression01,string progression02,string progression03,int score,Dictionary<string, string> fields = null,bool mergeFields = false	void
AddDesignEvent	string eventId, Dictionary<string, string> fields = null,bool mergeFields = false	void
AddDesignEventWithValue	string eventId,float value, Dictionary<string, string> fields = null,bool mergeFields = false	void
AddErrorEvent	ErrorSeverity severity, string message,Dictionary<string, string> fields = null,bool mergeFields = false	void
AddAdEvent	AdAction adAction,AdType adType,string adSdkName,string adPlacement, Dictionary<string, string> fields = null,bool mergeFields = false	void
IsRemoteConfigsReady	(no arguments)	bool
GetABTestingId	(no arguments)	string
GetABTestingVariantId	(no arguments)	string
GetRemoteConfigsValueAsString	string key,string defaultValue	string