Helika Unreal Engine SDK (0.3.0)

The Helika Unreal Engine SDK mirrors the functionalities of the Unity SDK, catering specifically to Unreal Engine game developers. This integration facilitates the seamless inclusion of Helika services into your games. By incorporating the Helika Unreal Engine SDK, you gain effortless access to the complete range of Helika capabilities, empowering you to construct robust and scalable solutions with ease.

Features

• Streamline integration with Helika services
• Access to a wide range of Helika APIs

📘

Current Version: 0.3.0

Installation

You can download the latest version of the Helika Plug-in from our github repository.

To install, Add the Plugin to your project directory and enable it from the plugins menu inside the editor.

Upgrading your version

You can download the latest version of the Helika Plugin from our github repository.

To upgrade the Helika SDK, Add the Plugin to your project directory and enable it from the plugins menu inside the editor.

❗️

Upgrading to v.0.3.0

Upgrading to v.0.3.0 has some breaking changes in the code. Please read through this doc to see which areas change. They will be marked.

Quick Start

You’ll need a Helika API Key in order to initialize the HelikaManager. Please reach out to your Client Success Manager in order to receive an API key for your organization.
After installing the plugin, Add in the required config values in Project Settings -> Plugins -> Helika_.

You'll need to set:

• Api Key which comes from https://portal.helika.io
• Game ID which is simply an identifier and filter for the set of events from this game
• Helika Environment to Localhost, Develop, or Production
• Telemetry to None, TelemetryOnly or All

Optionally:

• Set Print Events to Console (default: true)
• Set Player Id, which simply appends the specific player_id to all events. You can programatically add this at any time by calling HelikaManager.SetUserDetails()

The HelikaActor script inside the sample folder is just a simple script to show you how to initialize the Helika Manager and fire events.

Telemetry Level

Telemetry Level indicates the data that will be collected.

• None - No event is being sent to Helika. You would use this to test events locally. Make sure to have "Print Events To Console" checked
• TelemetryOnly - We will only collect event data. No device information is collected. (UserDetails and AppDetails objects will still be appended)
• All - We will collect user and device information in addition to game events.

Note: When it's set to Localhost, the helika events will only be printed in the Output Log. It will say whether the event is 'Sent' or 'Print Only'"

Programmatic Initialization

0.3.x update

Please make note of the initialization updates in 0.3.x. These are breaking changes going from 0.1.x. to 0.3.x

Here is a quick script to add somewhere in your initialization scripts.

In order to use the Helika SDK you need to add the following dependencies in your project build file and refresh your project.

PublicDependencyModuleNames.AddRange(
   new string[]
   {
      "Helika",
      "Json",
      "JsonUtilities"
   });

C++

// The HelikaManager is a singleton, so it only needs to be initialized once
// at the start of the game. Every subsequent use of the HelikaManager can simply
// use the UHelikaManager::Get()
void ATestActor::BeginPlay()
{
   Super::BeginPlay();


   HelikaManager = UHelikaManager::Get();
  
   TSharedPtr<FJsonObject> UserDetails = MakeShareable(new FJsonObject());
   UserDetails->SetStringField("user_id", “player_id_test”);
   UserDetails->SetStringField("email", "[email protected]");
     UserDetails->SetStringField("wallet", "0x8540507642419A0A8Af94Ba127F175dA090B58B0");
  
   HelikaManager->SetUserDetails(UserDetails);      


   TSharedPtr<FJsonObject> AppDetails = MakeShareable(new FJsonObject());
   AppDetails->SetStringField("platform_id", "Windows");
   AppDetails->SetStringField("client_app_version", "0.1.1");
   AppDetails->SetObjectField("server_app_version", nullptr);
   AppDetails->SetStringField("store_id", "EpicGames");
   AppDetails->SetObjectField("source_id", nullptr);
  
   HelikaManager->SetAppDetails(AppDetails);


   HelikaManager->InitializeSDK();

Blueprints

The HelikaManager is a singleton so it only needs to be initialized once at the start of the game.

Any data in the UserDetails and AppDetails is appended to events sent. UserDetails will only be added to events sent using HelikaManager.SendUserEvent(), but AppDetails will be appended to both HelikaManager.SendEvent() and HelikaManager.SendUserEvent() and its variations.

You can set UserDetails and AppDetails by calling HelikaManager.SetUserDetails() and HelikaManager.SetAppDetails() anytime you need to make changes to these objects. They will replace the existing details object.

You can reset the UserDetails by passing an object with "user_id" field set to null

C++

// Log out user
TSharedPtr<FJsonObject> UpdatedUserDetails = MakeShareable(new FJsonObject());
UpdatedUserDetails->SetObjectField("user_id", nullptr);
HelikaManager->SetUserDetails(UpdatedUserDetails);


// Clear and Reset User Details
const TSharedPtr<FJsonObject> LogoutEvent = MakeShareable(new FJsonObject());
LogoutEvent->SetStringField("event_type", "logout");
const TSharedPtr<FJsonObject> LogoutSubEvent = MakeShareable(new FJsonObject());
LogoutSubEvent->SetStringField("event_sub_type", "user_logged_out");
LogoutEvent->SetObjectField("event", LogoutSubEvent);
HelikaManager->SendUserEvent(LogoutEvent);


// Set New User info
TSharedPtr<FJsonObject> UpdatedUserDetails = MakeShareable(new FJsonObject());
UpdatedUserDetails->SetStringField("user_id", "new_player_id");
HelikaManager->SetUserDetails(UpdatedUserDetails);


// Clear and Reset User Details
const TSharedPtr<FJsonObject> LoginEvent = MakeShareable(new FJsonObject());
LoginEvent->SetStringField("event_type", "login");
const TSharedPtr<FJsonObject> LoginSubEvent = MakeShareable(new FJsonObject());
LoginSubEvent->SetStringField("event_sub_type", "user_logged_in");
LoginEvent->SetObjectField("event", LoginSubEvent);


HelikaManager->SendUserEvent(LoginEvent);

Blueprints

PII Tracking

By default, PII Tracking is set to False on initialization unless you set the TelemetryLevel to All. You can opt to enable or disable PII Tracking by calling HelikaManager.SetPIITracking(true). When setting the PII Tracking to true, you can force it to send an event to log PII: HelikaManager.SetPIITracking(true, true);

C++

bool bPIITracking = HelikaManager->GetPIITracking();
HelikaManager->SetPIITracking(!bPIITracking, true);

Blueprints

Sending Events

Once the HelikaManager is initialized somewhere, you can simply call the UHelikaManager::Get()->SendUserEvent() for user-specific events or UHelikaManager::Get()->SendEvent() for non user-specific events(s).

There are several different ways to send an event, please use whichever is most applicable to your application.

Review the HelikaActor.cpp / BP_HelikaActor file to get assistance in event sending procedures.

C++

// This is an example of sending a single user event
const TSharedPtr<FJsonObject> PlayerKillEvent = MakeShareable(new FJsonObject());
PlayerKillEvent->SetStringField("event_type", "player_event");
const TSharedPtr<FJsonObject> PlayerKillSubEvent = MakeShareable(new FJsonObject());
PlayerKillSubEvent->SetStringField("event_sub_type", "player_killed");
PlayerKillSubEvent->SetNumberField("user_id", 10);
PlayerKillSubEvent->SetNumberField("damage_amount", 40);
PlayerKillSubEvent->SetNumberField("bullets_fired", 15);
PlayerKillSubEvent->SetStringField("map", "arctic");
PlayerKillEvent->SetObjectField("event", PlayerKillSubEvent);


HelikaManager->SendUserEvent(PlayerKillEvent); 


// This is an example of sending multiple events at once
const TSharedPtr<FJsonObject> Event1 = MakeShareable(new FJsonObject());
Event1->SetStringField("event_type", "bomb_event");
const TSharedPtr<FJsonObject> Event1SubEvent = MakeShareable(new FJsonObject());
Event1SubEvent->SetStringField("event_sub_type", "bomb_planted");
Event1SubEvent->SetStringField("map", "arctic");
Event1SubEvent->SetStringField("team", "counter-terrorists");
Event1->SetObjectField("event", Event1SubEvent);


const TSharedPtr<FJsonObject> Event2 = MakeShareable(new FJsonObject());
Event2->SetStringField("event_type", "bomb_event");
const TSharedPtr<FJsonObject> Event2SubEvent = MakeShareable(new FJsonObject());
Event2SubEvent->SetStringField("event_sub_type", "bomb_diffused");
Event2SubEvent->SetStringField("map", "arctic");
Event2SubEvent->SetStringField("team", "counter-terrorists");
Event2SubEvent->SetNumberField("duration", 10210.121);
Event2->SetObjectField("event", Event2SubEvent);


TArray<TSharedPtr<FJsonObject>> EventArray;
EventArray.Add(Event1);
EventArray.Add(Event2);
HelikaManager->SendUserEvents(EventArray);


// This is an example of a non-user event. For Non-user events, we don't automatically append user information
const TSharedPtr<FJsonObject> WinEvent = MakeShareable(new FJsonObject());
WinEvent->SetStringField("event_type", "game_finished");
const TSharedPtr<FJsonObject> WinSubEvent = MakeShareable(new FJsonObject());
WinSubEvent->SetStringField("event_sub_type", "win_results");
WinSubEvent->SetStringField("winner", "counter-terrorists");
WinSubEvent->SetStringField("map", "arctic");
WinEvent->SetObjectField("event", WinSubEvent);


HelikaManager->SendEvent(WinEvent);

Blueprints

API Reference

Conventions

HelikaEnvironment

C++

UENUM(BlueprintType)
enum class EHelikaEnvironment : uint8
{
   HE_Localhost UMETA(DisplayName = "Localhost"),
   HE_Develop UMETA(DisplayName = "Develop"),
   HE_Production UMETA(DisplayName = "Production")
};

TelemetryLevel

C++

UENUM(BlueprintType)
enum class ETelemetryLevel : uint8
{
   TL_None UMETA(DisplayName = "None"),
   TL_TelemetryOnly UMETA(DisplayName = "TelemetryOnly"),
   TL_All UMETA(DisplayName = "All"),
};

Game Event Taxonomy

For our event processors to effectively parse your events, they must adhere to a specific set of guidelines

Example Event for SendUserEvents()

JSON

{
  "event_type": "user_download",
  "event": {
    "event_sub_type": "epic_games_download",
    "player_id": "user_1",
    "win_number": 1,
    "wallet": "0x4kd...."
  }
}

Required Info in the event taxonomy

Please make sure that you add an eventtype and event_sub_type to the event, otherwise, it will not be sent and will throw an error.

Automatic Data Capture

The Helika SDK automatically appends selected data fields in the event alongside your customized data event.

Methods

Change Log

V0.3.0

• Updated to Taxonomy 2.0
• Simplified Event Sending
• Added User and App Details Support
• Added sample usage file for easier understanding