Integrations

Unreal 4 SDK

SETUP

Marketplace Installation

  • Open the Epic Games Launcher
  • Click on Marketplace
  • Search for GameAnalytics
  • Click on the GameAnalytics plugin
  • Click on the Free button and accept the terms and conditions
  • Click on the Install to Engine button
  • Wait for the download to finish
  • The plugin is now installed

Verify plugin

Make sure the Plugin is enabled by clicking Settings → Plugins.
Check Installed → Analytics for GameAnalytics plugin.
Check Built-In → Analytics for enabling the Analytics Blueprint Library.

Add GameAanalytics as ProviderModuleName

Finally, add the following to your project’s DefaultEngine.ini file located in the Config folder.

Using GameAnalytics direct from C++ code

If you are planning to use the GameAnalytics SDK direct from C++ code you need to add GameAnalytics to PrivateDependencyModuleNames and PrivateIncludePathModuleNames in your project’s *.Build.cs file:

And include the GameAnalytics header file to wherever you are using the SDK:

Manual Installation

Download

Download the latest version of our plugin from this repository
here.

There are 2 ways of installing the plugin manually.

  • Integrating into the engine full source version (editor compiling)
  • Installing into a specific project (using pre-compiled editor)

For guidelines on how to install the plugin though Marketplace click [here](Marketplace Installation)

Integrating into the engine full source version (editor compiling)

When using the full source version you compile the Unreal Editor yourself. It is possible to add the plugin at this stage to be part of the engine and available for all projects created using that compiled version.

To do this navigate to your Unreal Engine 4 directory and place the GameAnalytics folder inside the folder \Engine\Plugins\Runtime\Analytics

Then compile the Engine Editor and the plugin is available.

Installing into a specific project (using pre-compiled editor)

A pre-compiled editor can be downloaded through the Epic Games Launcher or built from source. When GameAnalytics is not part of the editor it needs to be added to the specific project.

Add the GameAnalytics folder to a \Plugins subfolder in your specific project folder. If this Plugins subfolder doesn’t exist then create one.

Finally compile the project.

The project has to be a C++ project for the plugin to work.

Activating the plugin

  • Restart the Unreal Editor
  • Open the Plugins menu (Window > Plugins)
  • Under Analytics enable the GameAnalytics plugin
  • Also enable the Blueprint Analytics Framework (if you are using blueprint)

You will be prompted to restart the editor again.

Finally, add the following to your project’s DefaultEngine.ini file located in the Config folder.

Using GameAnalytics direct from C++ code

If you are planning to use the GameAnalytics SDK direct from C++ code you need to add GameAnalytics to PrivateDependencyModuleNames and PrivateIncludePathModuleNames in your project’s *.Build.cs file:

And include the GameAnalytics header file to wherever you are using the SDK:

Project Settings


To access the GameAnalytics settings you need to go to Project Settings and select the GameAnalytics plugin.

Account

On the account tab you can login to a GameAnalytics account directly in the editor. If you do not already have a GameAnalytics account you can sign up here.

Login through Project Settings allows you to select your studio and game for each platform, to automatically retrieve your game keys.

Game Key + Secret Key

For each platform you need to configure a set of game keys.

Game key is a unique identifier for your game.
secret key is used to protect event data from being tampered with as it travels to the GameAnalytics servers.

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]

The build version should be used for changing production builds of the game.
We recommend creating a separate game when implementing or testing the SDK.

Custom Dimensions

During gameplay it is possible to set values for 3 different custom dimensions. For each custom dimension it is needed specify a whitelist. You cannot set a custom dimension value unless it is specified here first.

For more information about custom dimensions go here.

Resource Types

When submitting resource events you specify a resource currency and resource item type. It is needed to specify a whitelist for each of these. You cannot submit a resource event using other values than specified here.

Use custom 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.

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.

Use the following piece of code to set the custom user id:

Or via Blueprint like this:

When using custom id you need to remember GameAnalytics will first be fully initialized when you have set the custom id. No events can be sent before GameAnalytics is fully initialized.

Info Log Build

The info log will output basic information about what is happening when your game is built for native.

Verbose Log Build

The verbose log will output the event JSON data that is being sent to the GameAnalytics servers when your game is built for native.

IOS & Android Builds


GameAnalytics works out-of-the-box with iOS & Android games. So you do not need to perform any additional steps when building your game for an iOS or Android device.

HTML5 Build


NOTE: At the moment HTML5 build only works with full source Unreal Engine until this pull request been merged into a released version of the Unreal Engine. You have to replace the following lines to Engine/Source/Programs/UnrealBuildTool/HTML5/HTML5ToolChain.cs:

with this:

Adding Events

An event should be added when an important action is happening in your game. Some very frequent events should be aggregated locally (sum) during a level and then submitted in one event (like coin pickups).

GameAnalytics cover general areas.

  • monetization (business)
  • virtual economy (resource)
  • progression

But also provide more flexibility in the design event.

Games are different and therefore the events that will make sense will be different.

Read more about events here. You will get the most benefit of GameAnalytics when understanding what and how to track.

Initialize SDK


To initialize the GameAnalytics SDK in Blueprint you must first call The Analytics Blueprint Library action called “Start Session”.

Note that you should call this action before sending any events.

The Start Session action alone is enough to track general user metrics such as DAU (Daily Active Users), MAU (Monthly Active Users), Retention, etc.

The SDK should only be initialised via blueprint. Initialisation via code is not available.

Business Events


Business events are used to track IAP transactions with real money.

Mobile games can be hacked and distributed illegally.
Hacking an app will often involve faking/simulating all purchase requests. This will result in several Business events being sent to GameAnalytics for transactions that never occurred.

GameAnalytics provide the option of receipt validation for each purchase sent to GA servers. This process can ensure that revenue metrics reflect the actual spending in your game.

Receipt validation is supported for the following stores.

  • App Store (iOS)
  • Google Play Store (Android)

Blueprint

A Business event should be set up in Blueprint as shown below (Android used in example).

The Analytics Blueprint Library action used is “Record Simple Currency Purchase with Attributes”.

Game Currency Type should be set to the currency code in ISO 4217 format.

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

The Attributes array should contain the following Analytics Event Attributes:

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 about App Store receipt here. null
autoFetchReceipt base64 string May replace receipt. Attempts to locate the latest receipt in iOS native code and submit the event if found. iOS7+ only. true
Android Fields Type Description
signature base64 string INAPP_DATA_SIGNATURE.null allowed.Read about Android signature here.
receipt base64 string INAPP_PURCHASE_DATA.Nil allowed.Read about Android receipt here.

Android receipt json schema

From C++ code

iOS:

Android:

All platforms:

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:

Here is how to get receipts and to use to send business events so they get marked as valid events:

Android

iOS

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

Read more information about the business event here.

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.

Blueprint

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

The Analytics Blueprint Library action used is “Record Simple Item Purchase with Attributes”.

ItemId should be set to the specific item bought.

The Attributes array should contain the following Analytics Event Attributes:

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.

From C++ code

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.

For more information on the resource event 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.

Blueprint

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

The Analytics Blueprint Library action used is “Record Progress with Full Hierarchy and Attributes”.

Progress Type should be set to the status of added progression (must be “start”, “complete” or “fail”).

The Progress Names array should contain the following values:

Field Type Required Description
progression01 string yes 1st progression (e.g. world01).
progression02 string no 2nd progression (e.g. level01).
progression03 string no 3rd progression (e.g. phase01).

The Attributes array may contain an Analytics Event Attribute named “value”, with an integer (can be used to track the player’s score).

From C++ code

For more information on the progression event 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.

Blueprint

An Error event should be set up in Blueprint as shown below.

The Analytics Blueprint Library action used is “Record Error with Attributes”.

Error should be set to the severity of the error recorded (must be “debug”, “info”, “warning”, “error” or “critical”).

The Attributes array should contain an Analytics Event Attribute named “message” with additional error information.

From C++ code

For more information on the error event go here.

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.

Blueprint

Here are three examples of how to set up Design events in Blueprint.

The Analytics Blueprint Library actions that can be used to send Design events are: “Record Event”, “Record Event with Attribute” and “Record Event with Attributes”.

For “Record Event” the Event Name is used to identify the event. Otherwise Attribute Name is used to identify the event, and the Attribute Value (which must be a float) is used as the event’s number value. This means that you can send multiple events with “Record Event with Attributes”, as shown in the example above.

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 32. (e.g. segment1:anotherSegment:gold).

From C++ code

For more information on the design event go here.

Custom Dimensions


Sets one of three custom dimensions. The value used must be defined in the GameAnalytics tab under Project Settings.

Blueprint

Here is an example of how to set a custom dimension in Blueprint.

The Analytics Blueprint Library action used to set a custom dimension is “Record Event with Attribute”.

Attribute Name must be set to either “custom1”, “custom2” or “custom3”. Attribute Value must be set to one of the available values for that custom dimension, defined in the GameAnalytics tab under Project Settings. To reset any of the current custom dimensions just set it to empty string.

From C++ code

Read more about custom dimensions here.

Set Facebook ID


If your game has Facebook integration you can submit the Facebook Id to GameAnalytics. You will then be able to get additional information about the types of players which play your game.

Blueprint

Here is an example of how to set the Facebook Id in Blueprint.

The Analytics Blueprint Library action used to set a custom dimension is “Record Event with Attribute”.

Attribute Name must be set to “facebook”. Attribute Value is used for the actual Facebook id.

From C++ code

Set Gender


If your game has information about the player’s gender you can submit this to GameAnalytics. You will then be able to get additional information about the types of players which play your game.

Blueprint

Here is an example of how to set the player’s gender in Blueprint.

The Analytics Blueprint Library action used to set a custom dimension is “Set Gender”.

Gender must be set to the player’s gender (allowed values are “male” or “female”).

From C++ code

Set Birth Year


If your game has information about the player’s birth year you can submit this to GameAnalytics. You will then be able to get additional information about the types of players which play your game.

Blueprint

Here is an example of how to set the player’s birth year in Blueprint.

The Analytics Blueprint Library action used to set a custom dimension is “Set Age”.

Age must be set to the player’s birth year (f.x. 1984).

From C++ code