Helika Web SDK Docs

The Helika SDK is a powerful toolkit for integrating Helika services into your applications. Implementing the Helika SDK, enables the ability to leverage the full capabilities of Helika and build robust and scalable solutions.

Features

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

📘

Current Version: 0.3.2

Installation

To install the Helika SDK, you can use npm:

npm install helika-sdk

Quick Start

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

Here's a quick example on how to get started with the Helika SDK:

import Helika, { DisableDataSettings, EventsBaseURL } from "helika-sdk"

var helika;

try {
	// Initialize the Helika SDK - it will throw if you use an invalid API key
  helikaSDK = new Helika.Events(
    'YOUR_API_KEY',
    'YOUR_GAME_ID', // alphanumeric, only underscore, no spaces, 
    EventsBaseURL.EVENTS_DEV
  );
} catch (e) {
	console.error("api key is invalid"); 
}

// Optional - if you want to disable Personal Identifiable Information Tracking due to compliance
async helikaSDK.setPIITracking(false);

// Set the default App Details. These will be appended to all events. 
helikaSDK.setAppDetails({
    platform_id: 'android', // Optional - android, ios, web, desktop, etc.
    client_app_version: '1.0.0', // optional - only if it's a client app
    server_app_version: '1.0.0', // optional - set only if the sdk is installed on the server
    store_id: 'steam', // optional
    source_id: 'facebook', // optional 
})

// Include any user identifying information that you'd like to keep track of such as any 
// emails, wallet addresses, player_id, group_id, usernames, etc.
helikaSDK.setUserDetails({
	user_id: '123456',
	email: '[email protected]',
	wallet_id: '0x4kd....'
})

// Start a session/create a new session which initiates the SDK instance with a
// sessionId which is required to fire events. This should only be called when 
// the user lands on the page. We store and re-use the session_id from the local
// storage, if present.
await helikaSDK.startSession();

// Instantiate events based on your game's event taxonomy
const events = [
  {
    event_type: 'user_register',  // required
    event: {                      // required
      event_sub_type: 'register', // required
      event_details: {
        // Client defined information
        event_label: "event_label",
        event_action: "event_action" 
      },
      win_number: 1,
      user_details: {
      	discord_id: "some_discord_id", // you can optionally add custom user_details information  
        twitter_id: 'twitterid'
      }
    }
  },
  {
    event_type: 'user_download',  // required
    event: {                      // required
      event_sub_type: 'download',
      event_details: {
        // Client defined information
        event_label: "event_label", // Type: varchar
        event_action: "event_action" # Type: varchar
      },
      timestamp: 12391989
    }
  }
];

// Asynchronously
// await helika.createEvent(events);

// Send an Event to Helika
helikaSDK.createEvent(events)
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.error(error);
  });

❗️

Upgrading from 0.2.x

There are significant differences between 0.2.x and 0.3.x. The following functions should be called before helikaSDK.startSession() is called:

• async helikaSDK.setPIITracking()
• helikaSDK.setAppDetails({ platform_id: 'android', // Optional - android, ios, web, desktop, etc. client_app_version: '1.0.0', // optional - only if it's a client app server_app_version: '1.0.0', // optional - set only if the sdk is installed on the server store_id: 'steam', // optional source_id: 'facebook', // optional })
• helikaSDK.setUserDetails({ user_id: '123456', email: '[[email protected]](mailto:[email protected])', wallet_id: '0x4kd....' })
• Replace any get/setPlayerId() with get/setUserDetails()
• Remove helikaSDK.setDataSettings() calls (if used)
• Remove helikaSDK.createUAEvent() calls (if used)

The 0.3.x version now implements our new standard Event Taxonomy. Please refer to:

API Reference

Conventions

The EventsBaseURL is an enum that dictates where to send all API requests. The SDK will handle the set-up for you. You just need to provide an API key and select whether it’s for production or development.
For testing purposes, we've added EVENTS_LOCAL which logs your events to console.log() instead of sending the events.

enum EventsBaseURL {
  EVENTS_LOCAL,
  EVENTS_DEV,
  EVENTS_PROD
}

Game Event Taxonomy

In order for our event processors to parse your events, they must adhere to the set guidelines below.

Example Event

{
  "event_type": "register",
  "event": {
    "event_sub_type": "user_register",
    "event_details": {
      "event_label": "event_label", 
      "event_action": "event_action" 
    },
    // Custom User details that weren't set with the default SetUserDetails() 
    "user_details": {
      "discord_id": "some_discord_id"
    }
    // Other details
    "win_number": 1,
  }
}

Default Data

App Details

The developer can set specific app details. helikaSDK.setAppDetails() adds default details for the app which will be included with all events. All of these are optional, but setting them enables better data quality and better analytics.

User Details

When a user logs in, the developer can set the user-specific details using helikaSDK.setUserDetails. The SDK automatically appends this information to the event in the user_details field. Adding more information enables better quality data and better analytics.

If a user does not authenticate and no user_id is sent to Helika, an Anonymous ID will be created on session_create allowing the required field to be satisfied. When the User Details is finally set, after authentication, Helika will associate the Anonymous ID with this authenticated user to provide consistency relating events back to a single user.

Personal Identifiable Information

The developer has the ability to disable PII (Personal Identifiable Information) tracking using async helikaSDK.setPIITracking(false) in order to comply with privacy regulations. This needs to get set before the StartSession() because the PII will be added or omitted in the session_created event.

If, during the session, the user decides to enable PII tracking, the developer can turn on PII Tracking and it will fire an event to grab PII.

Automatic Data Capture

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

🚧

Clearing Local Storage

We store some saved information such as session_id and the user's anon_id in local storage. Clearing the Local Storage will reset this information and cause new information to be generated.

Methods

Validation

It is recommended that your team verifies the events are being ingested correctly by sending a series of 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 received in
• 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 confirming test events appear in the data summary table, this report can be used to monitor your ongoing events and event volumes, as they are added.

License

The Helika SDK is released under the MIT License.