Docs > Unreal 4 SDK

Unreal 4 SDK

In this integration guide we will take you through the most important steps of instrumenting your game with the GameAnalytics Unreal SDK.

#

setup

Copy link to clipboard
#

Video Guide

Copy link to clipboard

#

Marketplace Installation

Copy link to clipboard

1. Download Plugin

  • 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

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

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

Copy link to clipboard

1. Download SDK

Download

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)

2a. 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.

  • Navigate to your Unreal Engine 4 directory and place the GameAnalytics folder inside the folder \Engine\Plugins\Runtime\Analytics

2b. 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.

3. 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:

 

#

Sign Up and Login

Copy link to clipboard

1. Account Creation

If you have not already, you can register for a GameAnalytics accounts via our online form here.

After you have signed up you will be asked to create a studio and a game. If your game is already published and on an app store you can search for it using the provided search field or else you can create it manually.

2. Login

On the Account tab you can Login to a GameAnalytics account directly in the editor.

Login through Project Settings allows you to select your studio and game for each platform. When selected the game key and the secret key will be automatically fetched and configured.

You can always locate the keys in our tool via game settings.

To use GameAnalytics you need a game key and a secret key for each platform you are using (iOS / Android).

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

Once a game has been created it can take a few minutes before the GameAnalytics servers will accept events for that game

#

unreal settings

Copy link to clipboard

You can access your game settings via Project Settings, then selecting GameAnalytics within the Plugins section.

#

Custom Dimensions

Copy link to clipboard

GameAnalytics support the use of 3 custom dimensions.

  • Custom01
  • Custom02
  • Custom03

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. Remember you have to set the custom dimensions before initialzing the SDK (but after setting the available custom dimensions) to be able to add the dimensions to the first session start event.

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

Copy link to clipboard

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.

#

Build

Copy link to clipboard

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.

#

Debug

Copy link to clipboard

Info Log Build

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

Verbose Log Builld

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

#

event tracking

Copy link to clipboard

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

If you are knew to GameAnalytics and our Events, please read our event guide here. You will get the most benefit of GameAnalytics when understanding what and how to track.

#

Start Session

Copy link to clipboard

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 Event

Copy link to clipboard

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

Blueprint Setup

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

Business event without validation:

The GameAnalytics action used is “Add Business Event”.

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

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:

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

Android (use “Add Business Event Android”)

iOS (use “Add Business Event IOS”)

So on Android receiptCipheredPayload contains the signature needed for the business events and 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 about App Store receipt here. null
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.

From C++ code

iOS:

Android:

All Platforms:

Business Events (with validation)

#

Resource Event

Copy link to clipboard
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 GameAnalytics action used is “Add Recource 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.

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 Event

Copy link to clipboard

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.

With progression 01:

With progression 01 and score:

With progression 01+02:

With progression 01+02 and score:

With progression 01+02+03:

With progression 01+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

From C++ code

For more information on the progression event go here.

#

Error Event

Copy link to clipboard

Used to track custom error events in the game. You can group the events by severity level and attach a message.

Blueprint Setup

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

The GameAnalytics action used is “Add Error Event”.

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

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

From C++ code

For more information on the error event go here.

#

Design Event

Copy link to clipboard

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 Setup

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

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

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

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

From C++ code

For more information on the design event go here.

#

command center

Copy link to clipboard

#

Configs

Copy link to clipboard

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

Blueprint Setup

From C++ code

To get values out of a populated Config use the following methods:

Blueprint Setup

From C++ code

If the specified key is not found in the Config it will return the default value either “normal” or “custom” default value.

More info Configs please see here

#

Experiments (A/B testing)

Copy link to clipboard

To manual check if the Experiment (CommandCenter) is ready (has been populated with values) you can call this:

Blueprint Setup

From C++ code

To get values out of a populated Experiment use the following methods:

Blueprint Setup

From C++ code

If the specified key is not found in the Expermines it will return the default value either “normal” or “custom” default value.

More info Experiments please see here

#

additional calls

Copy link to clipboard

#

Custom Dimensions

Copy link to clipboard

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

Blueprint Setup

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

The GameAnalytics action used to set a custom dimension is “Set Custom Dimension 01”, “Set Custom Dimension 02” and “Set Custom Dimension 03”.

Dimension 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 Custom ID

Copy link to clipboard

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.

#

Set Facebook ID

Copy link to clipboard

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 Setup

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

Copy link to clipboard

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 Setup

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

The GameAnalytics action used to set gender is “Set Gender”.

From C++ code

#

Set Birth Year

Copy link to clipboard

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 Setup

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

The GameAnalytics action used to set a custom dimension is “Set Birth Year”.

From C++ code

Contact support

We’ll get back to you ASAP.

Report a bug

Let us know more details.