Skip to content

Unreal Engine SDK

This SDK is in Beta

The Amplitude Analytics Unreal Engine SDK is in beta and currently supports projects targeting iOS, MacOS, or tvOS.

SDK installation

Install the SDK plugin

Install the Unreal Engine SDK by downloading the latest version of AmplitudUnreal.zip found on the GitHub releases page. Unzip it into a folder inside your Unreal project's Plugins directory.

mkdir -p Plugins/AmplitudeUnreal
unzip AmplitudeUnreal.zip -d Plugins/AmplitudeUnreal

Enable the SDK plugin in the editor

Open your project in the UE4 editor. Navigate to Settings > Plugins > Project > Analytics and make sure to enable AmplitudeUnreal.

screenshot of the plugin enabled

Set Amplitude as your analytics provider

Navigate to Settings -> Project Settings -> Analytics -> Providers and set the fields to Amplitude.

screenshot of the providers screen with Amplitude entered as the value

Add your API keys

Navigate to Settings -> Project Settings -> Analytics -> Amplitude and fill in the fields with your API key

screenshot of the API keys screen

Include analytics modules

In any file that involves instrumentation, you should include the necessary Unreal Engine analytics headers.

#include "Runtime/Analytics/Analytics/Public/Analytics.h"
#include "Runtime/Analytics/Analytics/Public/Interfaces/IAnalyticsProvider.h"

Usage and examples

The API of Amplitude Unreal follows the analytics provider interface defined by the Unreal Engine.

Logging basic events

Important notes about sending events

This SDK uses the HTTP V2 API and follows the same constraints for events. Make sure that all events logged in the SDK have the event_type field and at least one of device_id or user_id, and follows the HTTP API's constraints on each of those fields.

To prevent instrumentation issues, device IDs and user IDs must be strings with a length of 5 characters or more. If an event contains a device ID or user ID that's too short, the ID value is removed from the event. If the event doesn't have a user_id or device_id value, the upload may be rejected with a 400 status. Override the default minimum length of 5 character by passing the min_id_length option with the request.

Events represent how users interact with your app. For example, "Game Started" may be an action you want to note.

FAnalytics::Get().GetDefaultConfiguredProvider()->StartSession();
FAnalytics::Get().GetDefaultConfiguredProvider()->RecordEvent(TEXT("Game started"));
FAnalytics::Get().GetDefaultConfiguredProvider()->EndSession();

Logging events with properties

Events can contain properties. Properties give context about the event taken.

TArray<FAnalyticsEventAttribute> AppendedAttributes;
AppendedAttributes.Emplace(TEXT("Test Event Prop key1"), TEXT("Test Event value1"));
AppendedAttributes.Emplace(TEXT("Test Event Prop key2"), TEXT("Test Event value2"));
FAnalytics::Get().GetDefaultConfiguredProvider()->RecordEvent(TEXT("Game Started"), AppendedAttributes);

Setting user properties

User properties help you understand your users at the time they performed some action within your app.

The generic Unreal Engine IAnalyticsProvider supports a limited number of user properties.

FAnalytics::Get().GetDefaultConfiguredProvider()->SetLocation(TEXT("Test location"));
FAnalytics::Get().GetDefaultConfiguredProvider()->SetGender(TEXT("Test gender"));
FAnalytics::Get().GetDefaultConfiguredProvider()->SetAge(TEXT(27));

Setting custom user IDs

If your app has its own login system that you want to track users with, use SetUserId to set a custom user ID.

FAnalytics::Get().GetDefaultConfiguredProvider()->SetUserID(TEXT("test123@test.com"));

Last update: 2022-07-18