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

📘

Current Version: 0.1.5

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 AsyncAwaitUtil) that you already in your project.

Quick Start

You’ll need a Helika API Key in order to instantiate the Helika.EventManager. Please reach out to [email protected] 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 the Api Key, Game ID and set the Helika Env to either Localhost, Develop, or Production

You can also programmatically set the Player ID at any time. It is simply appended to all sent events.

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

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
async Task Start()
{
  eventManager = EventManager.Instance;
  await eventManager.Init(apiKey, gameId, HelikaEnvironment.Develop, true);
  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
async 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" }
    };
    await 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 }
    };
    await 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 };
    await eventManager.SendCustomEvents(uniqueEvents);
    
    // you can also send a single Custom event using Newtonsoft.Json.Linq.JObjects
    await eventManager.SendCustomEvent(addPointsEvent1);
  }
}

API Reference

Conventions

HelikaEnvironment

    public enum HelikaEnvironment
    {
        Localhost,
        Develop,
        Production
    }

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.