Event Tracking

GameAnalytics features the following event types:

Event	Description
Ad	Ads shown and clicked, fill rate.
Business	In-App Purchases supporting receipt validation on GA servers.
Design	Submit custom event id’s. Useful for tracking metrics specifically needed for your game.
Error	Submit exception stack traces or custom error messages.
Health	Automatically submits health metrics related to your game such as FPS.
Impression	Impression data from different ad networks
Progression	Level attempts with Start, Fail & Complete event.
Resource	Managing the flow of virtual currencies - like gems or lives

tip

Business Events

Business events are used to track IAP (real money transactions inside your game). With GameAnalytics for Unreal you can send events using either blueprints or C++.

Business Events in Blueprints

You can add a business event without validation as shown below:

The GameAnalytics action used is “Add Business Event”. Game Currency Type should be set to the currency code in ISO 4217 format.

The currency Amount should be set to the amount in cents (or the lowest currency denominator).

Receipt validation is supported for the following stores:

App Store (iOS)
Google Play Store (Android)

Get Receipts Using SDKBOX Unreal IAP (Android and iOS)

It is assumed that you have already set up and configured SDKBOX IAP correctly, if not please go here for more information on how to do this.

Make sure you have enabled user side verification:

Now depending on your platform use Add Business Event Android or Add Business Event iOS:

On Android receiptCipheredPayload contains the signature needed for the business events and on iOS receiptCipheredPayload is the receipt.

For iOS (iOS7+ only) you can also auto-fetch receipts like this (use “Add Business Event and Auto Fetch Receipt”).

Field	Type	Description	Example
itemType	string	The type / category of the item.	GoldPacks
itemId	string	Specific item bought.	1000GoldPack
cartType	string	The game location of the purchase.	EndOfLevel

iOS Fields	Type	Description	Example
receipt	base64 string	The App Store receipt. Nil allowed. Read more about App Store receipt here.	null

| Android Fields | Type | Description | | -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | signature | base64 string | INAPP_DATA_SIGNATURE. null allowed. | Read more about Android signature here. | | receipt | base64 string | INAPP_PURCHASE_DATA. Nil allowed. Read more about Android receipt here. |

Business Events in C++

Due to differences in receipts you will have to call different functions for iOS and Android.

iOS

On iOS you only have to pass the receipt, make sure to wrap your code around a define check so it's only called for iOS.

#if PLATFORM_IOS
UGameAnalytics::addBusinessEvent("USD", 99, "coinPack", "coinPack100", "shop", "testReceipt");
#endif

Android

On Android you will need to also pass the signature (INAPP_DATA_SIGNATURE, check the table above for more information)

#if PLATFORM_ANDROID
UGameAnalytics::addBusinessEvent("USD", 99, "coinPack", "coinPack100", "shop", "testReceipt", "testSignature");
#endif

Other Platforms

Since other platforms do not support receipts, you can just send a generic business event as showcased below. In case you need to add extra data (like a receipt for another platform), please consider adding a custom event field.

UGameAnalytics::addBusinessEvent("USD", 99, "coinPack", "coinPack100", "shop");

Custom Business Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::addBusinessEvent("USD", 99, "coinPack", "coinPack100", "shop", fields);

tip

For more information on custom event fields and raw data export go here.

tip

For more information about the business event go here.

Ad Events

The GameAnalytics ad event needs to be called when certain events happen for the implemented ad sdk’s.

An ad sdk has callback methods activating code when certain things are activated (like ad show or ad clicked). To use the ad event it is need to call the GameAnalytics SDK when these delegates are called.

Ad Events in Blueprints

The GameAnalytics action used is “Add Ad Event”, “Add Ad Event with Duration” or “Add Ad Event with No Ad Reason”.

Field	Type	Description	Example
adAction	enum	A defined enum for ad action (for example clicked).	EGAAdAction::clicked EGAAdAction::show EGAAdAction::failedshow EGAAdAction::rewardreceived
adType	enum	A defined enum for ad type (for example interstitial).	EGAAdType::Video EGAAdType::rewardedvideo EGAAdType::playable EGAAdType::interstitial EGAAdType::offerWall EGAAdType::banner
adSdkName	string	Name of the Ad/Ad mediation SDK.	admob
adPlacement	string	Identifier of ad in the game or the placement of it.	`level_complete_ad`
adPlacement	string	Identifier of ad in the game or the placement of it.	`level_complete_ad`
duration	int	Optional. Only used for video ads to track how long the user watched the video for.	10
noAdReason	enum	Optional. Used to track the reason for not being able to show an ad when needed (for example no fill).	EGAAdError::unknown EGAAdError::offline EGAAdError::nofill EGAAdError::internalerror EGAAdError::invalidrequest EGAAdError::unabletoprecache

Ad Events in C++

The C++ function uses the same parameters as the Blueprint function. You just have to call UGameAnalytics::AddAdEvent (or its variations) with the required parameters as shown below:

UGameAnalytics::AddAdEvent(EGAAdAction::show, EGAAdType::interstitial "admob", "level_end");
UGameAnalytics::AddAdEventWithDuration(EGAAdAction::show, EGAAdType::video, "admob", "level_end", 5000);
UGameAnalytics::AddAdEventWithNoAdReason(EGAAdAction::failedshow, EGAAdType::interstitial, "admob", "level_end", EGAAdError::nofill);

Custom Ad Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::AddAdEventWithNoAdReason(EGAAdAction::failedshow, EGAAdType::interstitial, "admob", "level_end", EGAAdError::nofill, fields);

tip

For more information on custom event fields and raw data export go here.

tip

For more information about Ad Events go here.

Impression Events

Impression events are only supported by the android and iOS platforms. Not all sdks will offer Unreal support (whilist support for iOS, android and unity is much more common).

tip

For more information about the iOS impression events go here.

For more information about the android impression events go here

tip

Resource Events

Resources events are used to track your in-game economy. From setting up the event you will be able to see three types of events in the tool. Flow, the total balance from currency spent and rewarded. Sink is all currency spent on items, and lastly source, being all currency rewarded in game.

Resource Events in Blueprints

The GameAnalytics action used is “Add Resource Event”. ItemId should be set to the specific item bought.

Field	Type	Required	Description
flowType	enum	yes	Add (source) or substract (sink) resource.
currency	string	yes	One of the available currencies set in Project Settings for the GameAnalytics plugin. This string can only contain [A-Za-z] characters.
itemType	string	yes	One of the available item types set in Project Settings for the GameAnalytics plugin.

Resource Events in C++

UGameAnalytics::addResourceEvent(EGAResourceFlowType::sink, "gold", 1, "boost", "rainbowBoost");

danger

Be careful to not call the resource event too often! In a game where the user collect coins fairly fast you should not call a Source event on each pickup. Instead you should count the coins and send a single Source event when the user either completes or fails the level.

Custom Resource Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::addResourceEvent(EGAResourceFlowType::sink, "gold", 1, "boost", "rainbowBoost", fields);

tip

For more information on custom event fields and raw data export go here.

tip

For more information about Resource Events go here

Progression Events

Progression events are used to measure player progression in the game. They follow a 3 tier hierarchy structure (world, level and phase) to indicate a player’s path or place.

Progression Events in Blueprints

A Business event should be set up in Blueprint as shown below.

With progression01:
With progression01 and score:
With progression01+02:
With progression01+02 and score:
With progression01+02+03:
With progression01+02+03 and score:

The GameAnalytics action starting with “Add Progression Event with*”.

Field	Type	Required	Description
progressionStatus	enum	yes	`Start`, `Complete` or `Fail`
progression01	string	yes	1st progression (e.g. `world01`).
progression02	string	no	2nd progression (e.g. `level01`).
progression03	string	no	3rd progression (e.g. `phase01`).
score	int	no	Score of the attempt

caution

At least progression01 must be set for such events (an empty value is not allowed).

info

Progressions need to be set in order (e.g: you cannot have only progression01 and progression03, nor progression02 and progression03, you are required to start from 01 and continue)

Progression Events in C++

UGameAnalytics::addProgressionEvent(EGAProgressionStatus::start, "level", "wildWest", "day1");
UGameAnalytics::addProgressionEvent(EGAProgressionStatus::complete, "level", "wildWest", "day1", 3);

//example of progression event without using progression02 nor progression03
UGameAnalytics::addProgressionEvent(EGAProgressionStatus::complete, "level1", "", "", 3);

Custom Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::addProgressionEvent(EGAProgressionStatus::complete, "level1", "", "", 3, fields);

tip

For more information on custom event fields and raw data export go here.

Error Events

Used to track custom error events in the game. This event should be used when something goes wrong inside the game's logic (also note that unhandled exceptions & crashes will be automatically sent over as error events). It is possible to group the events by severity level and attach a message.

Error Events in Blueprints

The GameAnalytics action used is “Add Error Event”.

Error should be set to the severity of the error recorded. The following severity levels are accepted:

Debug
Info
Warning
Error
Critical

Field	Type	Required	Description
severity	enum	yes	`Debug`, `Info`, `Warning`, `Error` or `Critical`
message	string	no	Custom error message

Error Events in C++

The C++ function will take the same parameters as the blueprint function.

UGameAnalytics::addErrorEvent(EGAErrorSeverity::error, "failed to load level");

Custom Error Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::addErrorEvent(EGAErrorSeverity::warning, "invalid score value", fields);

tip

For more information on custom event fields and raw data export go here.

tip

Design Events

Used to track any type of design event that you want to measure, f.x. GUI elements or tutorial steps. Custom dimensions are not supported for design events.

Design Events in Blueprints

The GameAnalytics actions that can be used to send Design events are: “Add Design Event” and “Add Design Event with Value”.

info

The event name is a String which can consist of 1 to 5 segments. Segments are seperated by ‘:’ and segments can have a max length of 64 characters. (e.g. "segment1:anotherSegment:gold").

Field	Type	Required	Description
eventId	string	yes	Event id
value	float	no	Optional custom value

Design Events in C++

You can also call a design event directly from C++ using the same parameters:

UGameAnalytics::addDesignEvent("Enemy:Killed", 3);

Custom Design Event Fields

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. Here is an example of how to use it:

TSharedRef<FJsonObject> fields = MakeShareable(new FJsonObject());
fields->SetNumberField(TEXT("test"), 100);
fields->SetStringField(TEXT("test2"), TEXT("hello_world"));

UGameAnalytics::addDesignEvent("Enemy:Killed", 3, fields);

tip

For more information on custom event fields and raw data export go here.

tip

For more information on the design event go here.

Event Tracking

Business Events​

Business Events in Blueprints​

Get Receipts Using SDKBOX Unreal IAP (Android and iOS)​

Business Events in C++​

iOS​

Android​

Other Platforms​

Custom Business Event Fields​

Ad Events​

Ad Events in Blueprints​

Ad Events in C++​

Custom Ad Event Fields​

Impression Events​

Resource Events​

Resource Events in Blueprints​

Resource Events in C++​

Custom Resource Event Fields​

Progression Events​

Progression Events in Blueprints​

Progression Events in C++​

Custom Event Fields​

Error Events​

Error Events in Blueprints​

Error Events in C++​

Custom Error Event Fields​

Design Events​

Design Events in Blueprints​

Design Events in C++​

Custom Design Event Fields​

Business Events

Business Events in Blueprints

Get Receipts Using SDKBOX Unreal IAP (Android and iOS)

Business Events in C++

iOS

Android

Other Platforms

Custom Business Event Fields

Ad Events

Ad Events in Blueprints

Ad Events in C++

Custom Ad Event Fields

Impression Events

Resource Events

Resource Events in Blueprints

Resource Events in C++

Custom Resource Event Fields

Progression Events

Progression Events in Blueprints

Progression Events in C++

Custom Event Fields

Error Events

Error Events in Blueprints

Error Events in C++

Custom Error Event Fields

Design Events

Design Events in Blueprints

Design Events in C++

Custom Design Event Fields