Helika Unity SDK Docs

The Helika Unity SDK mirrors the functionalities of the Web SDK, catering specifically to Unity game developers. This integration facilitates the seamless inclusion of Helika services into your games. By incorporating the Helika Unity 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

📘

Last Version: 0.2.1

Installation

You can download the Helika.unitypackage from our github repository.

To install, open your Unity game in unity hub. Go to Assets->Import Package-> Custom Package , navigate to the folder where you stored the Helika.unitypackage file, and select it.

Feel free to uncheck plugins (like Newtonsoft and PlayServicesResolver) that you don't need or is already in your project.

Upgrading your version

You can download the Helika.unitypackage from our github repository.

To upgrade the Helika SDK, open your Unity game in unity hub. Go to Assets->Import Package-> Custom Package , navigate to the folder where you stored the Helika.unitypackage file, and select it.

You can also drag and drop the downloaded unitypackage file in the Unity Editor.

❗️

Upgrading to v.0.2.0

Upgrading to v.0.2.0 has some breaking changes in the code. Please make sure you update the EventManager.Init() calls and to make sure to add TelemetryLevel Enum.

Quick Start

You’ll need a Helika API Key in order to instantiate the Helika.EventManager. Please reach out to your Client Success Manager in order to receive an API key for your organization.

To instantiate an object, you can simply select an object in your scene and select Add Component in the Inspector.

Select the Helika Asset Script

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 Env 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 EventManager.SetPlayerId()

The HelikaAssetScript will initialize and instantiate the Helika.EventManager. If you choose not to use the script, please look at the Programmatic Initialization section.

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 user and device information is collected.
• 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 Console. It'll say "Event Sent:" but, what it really means is "This is the event that would have been sent." This will be changed in the next release.

Programmatic Initialization

If you chose not to add the HelikaAssetScript component to a game object, you can add the following script somewhere in your initialization scripts.

// The EventManager is a singleton, so it only needs to be initalized once
// at the start of the game. Every subsequent use of the EventManager can simply
// use the EventManager.Instance
void Start()
{
  eventManager = EventManager.Instance;
  eventManager.Init(apiKey, gameId, HelikaEnvironment.Develop, TelemetryLevel.All, false);
  eventManager.SetPlayerID(playerId);
}

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

Sending Events

Once the EventManager is initialized somewhere, you can simply call the await EventManager.Instance.SendEvent() or await EventManager.Instance.SendEvents() whenever you need to send an event(s).

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

Review the HelikaAssetScript.cs file to get assist in event sending procedures.

// You can send an event any time in your game
void Update()
{
  // In this example, we send it when the user presses the "Space" key
  if (Input.GetKeyDown("space"))
  {
    // These are the Event Object. They are free-form JObjects. You can add as 
    // many properties in the "event" object as you would like. We do require
    // that "event_type" is set.
    
    // In most cases, you will use eventManager.SendEvent() or eventManager.SendEvents()
    
    // 1. This is an example of sending a single event with a Dictionary<string, object>
    Dictionary<string, object> dictionary = new Dictionary<string, object>
    {
      { "user_id", 10 },
      { "wallet_address", "0x8540507642419A0A8Af94Ba127F175dA090B58B0" }
    };
    eventManager.SendEvent("connect_wallet", dictionary);

    // 2. This is an example of sending multiple instances of a single event with Dictionary<string, object>
    Dictionary<string, object> evt1 = new Dictionary<string, object>
    {
      { "user_id", 10 },
      { "source", "win" },
      { "points", 15 }
    };
    Dictionary<string, object> evt2 = new Dictionary<string, object>
    {
      { "user_id", 10 },
      { "source", "top_3_player" },
      { "points", 5 }
    };
    eventManager.SendEvents("add_points", new Dictionary<string, object>[] { evt1, evt2 });

    // Alternatively, if you wish to send whole game events and overwrite automatically added properties
    // such as `game_id`, you can use the EventManager.SendCustomEvent() and EventManager.SendCustomEvents()
    // In most cases, use EventManager.SendEvents()
    // 3. This is an example of how to send Custom events with Newtonsoft.Json.Linq.JObject
    JObject addPointsEvent1 = new JObject(
      new JProperty("event_type", "add_points"),
      new JProperty("event", new JObject(
        new JProperty("user_id", 10),
        new JProperty("source", "top_3_player"),
        new JProperty("points", 5)
      ))
    );
    // This event has no 'event' data. We automatically generate it.
    JObject noDataEvent = new JObject(
      new JProperty("event_type", "no_data_event")
    );
    // This event overwrites the `game_id` field
    JObject specialStatsEvent = new JObject(
      new JProperty("game_id", "special_game_id_for_stats_only"),
      new JProperty("event_type", "unique_event_stats"),
      new JProperty("event", new JObject(
        new JProperty("user_id", 10),
        new JProperty("stats", 1000)
      ))
    );
    JObject[] uniqueEvents = new JObject[] { addPointsEvent1, noDataEvent, specialStatsEvent };
    eventManager.SendCustomEvents(uniqueEvents);
    
    // you can also send a single Custom event using Newtonsoft.Json.Linq.JObjects
    eventManager.SendCustomEvent(addPointsEvent1);
  }
}

API Reference

Conventions

HelikaEnvironment

public enum HelikaEnvironment
{
  Localhost,
  Develop,
  Production
}

TelemetryLevel

public enum TelemetryLevel
{
  None,
  TelemetryOnly,
  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 SendEvents()

{
  "player_id": "user_1",
  "win_number": 1,
  "wallet": "0x4kd...."
}

Example Whole Event for SendCustomEvents()

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

Automatic Data Capture

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

Methods

Platforms

Requirements:

• Android API 16
• iOS Target 12.4
• Xcode 14.1
• Unity 2019.4
• Scripting Runtime 4.x Equivalent

Supported Platforms:

• Android
• iOS
• Linux
• MacOS
• WebGL
• Windows Desktop
• Windows Store (UWP)
• VR Hardware:
  • Oculus Rift
  • Oculus Quest
  • HTC Vive
  • Valve Index

iOS

There are a few optional settings that may be adjusted that can be set before EventManager.Init() is called.

Validation

It is recommended that you verify events are being ingested correctly by sending some test events via the SDK. Successfully sent events should have a 200 status response.

Check within your portal for the events to appear in the Data Ingestion Summary.

The Data Ingestion Summary report can be found in the side menu:

• Data Summary > Data Ingestion Summary

The Data Ingestion Summary will display information such as:

• Which environment the events are being sent to
• Total Event Volumes
• Types, and Sub Types Seen
• A table for the raw event stream, with raw payload.

🚧

Ingestion Delays

Please expect up to the following delays during event processing, before results are populated:

• Production: 15 minutes
• Development: 2 hours

After seeing some test events appear, this report can be used to monitor your ongoing events and event volumes, as they are added.

Change Log

v0.2.0

• Removed AsyncAwait library
• Added TelemetryLevel Enum
• Updated EventLogs