Telemetry

Overview

The AccelByte Game Telemetry service acts as a scalable event data ingestion pipeline for your game, to send events into a designated streaming pipeline using an HTTP based REST API. With this service, you can collect and analyze player data and use it to inform future design decisions.

How it Works

The diagram below gives a basic overview of how the Game Telemetry service works:

telemetry

The Game Telemetry SDK sends events to be tracked into the Game Telemetry pipeline. After that, the Game Telemetry pipeline sends events to Kafka. Kafka Connect then pulls the events from Kafka and passes them to the designated data warehouse and data visualization tools.

Tutorials

Set Up the Data Warehouse

To be able to receive events and the player actions log, you have to set up a data warehouse. The Game Telemetry service supports several different data warehouses by default, and AccelByte can work with you to integrate a data warehouse that we don’t yet support.

Redshift

We’ll create a connector for you in Kafka Connect to pull event data from Kafka and write the data to Redshift. Nested data will be flattened in the Game Telemetry pipeline before getting pushed into Kafka. Each payload attached to the events will be converted into a Redshift column.

Integration Requirements

AccelByte can integrate the Game Telemetry pipeline with Redshift for you. To do so, you’ll need to send us the following information:

  • Redshift credentials
  • Redshift database name
  • Redshift table name

After we input that information into Kafka Connect, the connector will be created and the pipeline will automatically send game Game Telemetry data to Redshift.

S3

Integration Requirements

AccelByte can integrate the Game Telemetry pipeline with S3 for you. To do so, you’ll need to send us the following information:

  • AWS Credentials
  • Bucket name

After we input that information into Kafka Connect, the pipeline will automatically send Game Telemetry data to your S3 bucket.

Snowflake

To help you use our Game Telemetry service with Snowflake, we’ll provide you with Kafka Connect, Kafka Connect UI, Snowflake JDBC, and Snowflake Kafka Connector.

Integration Requirements

AccelByte can integrate the Game Telemetry pipeline with Snowflake for you. To do so, you’ll need to send us the following information:

  • Database name
  • Schema Name
  • Username
  • Snowflake URL

After we input that information into Kafka Connect, the pipeline will automatically send the event data to Snowflake.

Send Event

With our Game Telemetry service, you can track and log players' actions within the game by sending an event to be tracked to the game’s streaming pipeline. To track those actions a player session is required, so you must enable your players to create an account in your game before you can use this feature.

Send Event In the API

To send an event to the designated streaming pipeline, follow these steps.

  1. Use the Protected Save Events: POST - ​/game-telemetry​/v1​/protected​/events endpoint.

  2. Fill in the Request Body.

    • Input the EventNamespace with the game namespace.
    • Input the EventName with the name of the event e.g. player_killed, mission_accomplished.
    • Input the Payload with an arbitrary JSON of the event. Here are some examples of the payload for different use cases:
    • If you want to track player login and logout, you can use the following reference for your request body.
    Player Login
    {
    "EventName" : "player_logged_in",
    "EventNamespace" : "abshooter", // Game Namespace
    "Payload": {
    "GameSessionId" : "generated after the game client is executed",
    "UserId" : "could be obtained from player's credential information",
    "LoginSessionId" : "generated after the player has been logged in",
    "LoginType" : "[USERNAME, LAUNCHER, STEAM, etc..]",
    "GameVersion" : "our game release version",
    "SDKVersion" : "version of AccelByte SDK in the game's project",
    "DSTargetVersion" : "version of dedicated server image",
    "Platform" : "[WINDOWS, LINUX, etc..]"
    }
    }
    Player Logout
    {
    "EventName" : "player_logged_out",
    "EventNamespace" : "abshooter", // Game Namespace
    "Payload": {
    "GameSessionId" : "generated after the game client is executed",
    "UserId" : "could be obtained from player's credential information",
    "LoginSessionId" : "generated after the player has been logged in",
    "LoginSessionDuration" : "time unit is in minutes"
    }
    }
    • If you want to track when matchmaking starts and ends, you can use the following reference for your request body.
    Matchmaking Start
    {
    "EventName" : "player_match_start",
    "EventNamespace" : "abshooter", // Game Namespace
    "Payload": {
    "GameSessionId" : "generated after the game client is executed",
    "UserId" : "could be obtained from player's credential information",
    "MatchId" : "obtained from lobby matchmaking service",
    "ConnectToLocal" : [true, false], // Is using local DS
    "GameMode" : "chosen game mode for current match"
    }
    }
    Matchmaking End
    {
    "EventName" : "player_match_end",
    "EventNamespace" : "abshooter", // Game Namespace
    "Payload": {
    "GameSessionId" : "generated after the game client is executed",
    "UserId" : "could be obtained from player's credential information",
    "MatchId" : "obtained from lobby matchmaking service",
    "IsWinner" : [true, false], // Is the player win
    "EndReason" : "cause of end match"
    }
    }
    • If you want to detect a player’s active status on the server, you can use the following reference for your request body.
    Player Heartbeat
    {
    "EventName" : "player_heartbeat",
    "EventNamespace" : "abshooter", // Game Namespace
    "Payload": {
    "GameSessionId" : "generated after the game client is executed",
    "UserId" : "could be obtained from player's credential information",
    "IsServer" : [true, false] // Is it in the server
    }
    }
    • The Event Timestamp will be generated automatically by the Game Telemetry in ISO 8601 format, e.g. 2021-01-05T05:04:08.775Z.
    • The Event ID will be generated automatically by the Game Telemetry. Upon successful request, the event will be sent to the designated streaming pipeline for tracking.

Send Event Using the SDK

The following function signature can also be used to send an event. The returned data will be displayed in your data warehouse, where you’ll be able to customize its visualization.

FJsonObject Payload;
Payload.SetStringField("someString", "someString");
Payload.SetNumberField("someInt", i);
Payload.SetBoolField("someBool", true);
FAccelByteModelsTelemetryBody TelemetryBody;
TelemetryBody.EventName = "ExampleEvent";
TelemetryBody.EventNamespace = "GameNamespace";
TelemetryBody.Payload = MakeShared<FJsonObject>(Payload);
bool bTelemetryEventSent = false;
FRegistry::GameTelemetry.Send(
TelemetryBody,
FVoidHandler::CreateLambda([&]()
{
UE_LOG(LogTemp, Log, TEXT(" Success"));
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
UE_LOG(LogTemp, Fatal, TEXT(" Error. Code: %d, Reason: %s"), ErrorCode, *ErrorMessage);
})
);

Whats Next