What is the Events API?

The Events API is a new API to send Telemetry and PlayStream events to PlayFab for later analysis or reactive programming (or event-driven architectures).

The Events API supersedes the legacy Client Analytics API. You can, however, still use the legacy API for convenience.

But this article details why you should default to the new Events API 😊

Events API vs Legacy Events API

The legacy API was designed for ease of use in client applications. It provides a number of convenient endpoints to ingest data pertaining to a certain context (e.g. Player, Character etc) into PlayStream.

However, the way the legacy API works is that

• you can only ingest one event per call
• poses limited ingestion capabilities (API rate limits, client HTTP overhead)
• it does not support Telemetry Events
• it does not support the Entity Programming Model

The Events API resolves all of the above limitations of the legacy API. You can batch multiple events in one request, massively increasing the amount of Events you can ingest into PlayFab while at the same time saving you money and reducing the overall bandwidth used on the client-side. This is particularly important in mobile scenarios. It also supports the Entity Programming Model.

The biggest advantage, however, is likely the costs savings by enabling you to use Telemetry Events. We will differentiate in the next section.

PlayStream & Telemetry

You have read PlayStream and Telemetry a couple of times now - but what are these?

PlayStream and Telemetry share the fundamental design. You can think of them as arbitrary events pertaining to a specific Entity (Title Player, Character etc.), holding a list of key-value pairs as payload.

When you send any of these events to PlayFab, PlayFab will ingest them into it's data lake for you to later analyse with PlayFab's built-in or external tools.

While the two event types look the same when you send them, there is a very big difference when they "arrive" at PlayFab:

• Telemetry Events are just ingested into a data lake and you can then run analytics on them
• PlayStream Events can be reacted upon after they arrive. More on that below.

Example: Sending Telemetry Events

This is how you send a Telemetry Event in the Godot engine using (my own) godot-playfab addon. The Payload is completely arbitrary JSON:

func _on_WriteTelemetryDirectButton_pressed():
    var payload = {
        "Action": "_on_WriteTelemetryDirectButton_pressed"
    }
    
    PlayFabManager.event.write_title_player_telemetry_event(EVENT_NAME_TELEMETRY, payload)

And the unity version:

EventsModels.WriteEventsRequest request = new EventsModels.WriteEventsRequest();
request.Events = new List<EventsModels.EventContents>();

// Some metadata (required)
EventsModels.EventContents eventInfo = new EventsModels.EventContents();
eventInfo.Name = "unity_client_api_error_occurred";
eventInfo.EventNamespace = eventNamespace;
eventInfo.Entity = entityKey;
eventInfo.OriginalTimestamp = DateTime.UtcNow;

// Custom payload
var payload = new Dictionary<string, object>();
payload["ErrorCode"] = errorCode;
payload["ErrorType"] = type;
eventInfo.Payload = payload;

request.Events.Add(eventInfo);
var result = await eventApi.WriteTelemetryEventsAsync(request);

Working with the PlayStream

PlayStream is different in the way that PlayStream events can be used to react to them in near-realtime: you can not only analyse them after the fact with PlayFab's analytics capabilities - but you can also use them for event-driven architectures and reactive programming!

For instance, you can set up a Rule in PlayFab to run an Azure Function or gift an item if a specific event is appearing in the PlayStream. Check out my in-depth walk-through on how to do this - or have a look at our example project, where we used PlayStream to implement a Match History!

⚠️ Caution: Do not block on PlayStream events, e.g. waiting in your game UI for an event to appear in the PlayStream! PlayStream events are not real-time!

Built-in events

Even without implementing your own events, PlayFab already collects a lot of data for you just through built-in events triggered by API usage. For example, whenever a user logs in, events are generated. This data will be available for you to use in analytics, but also - just like your own events - can be used for automation or segmentation of users. When looking at segmentation, PlayFab has already pre-made segmentation for the most common use-cases like "Lapsed players", which shows you a list of users who have not been logging in since more than 30 days.

Using Events

Once you ingested Events through the API, whether by creating your own or through built-in facilities, you can start using the data in multiple ways:

Analysing Telemetry

Using PlayFab's built-in analytics capabilities, you can analyse player behaviour or your system's performance. If you require even more data analytics capabilities, you can also export the data!

Title Overview

When you open the PlayFab Game Manager for a given Title, the first page will always be the Title Overview. As you can see, PlayFab is already presenting you with a dashboard based on built-in events!

If you switch to the next Tab, PlayStream Monitor, you can see PlayStream events appearing in near-realtime as PlayFab ingests them, so you can inspect them and can even see where they appear on the world map.

Dashboards

A recent addition to the GameManager (and currently in public preview) is the Trends tab in the Dashboards section. There, PlayFab uses built-in events to provide you with a few important trends to see how your game is performing:

On the second tab of the Dashboards pane, you can view and download reports. You can also click on a report and get an awesome, detailed dashboard for it!

Data

In the Data section of the Game Manager, you can go really deep. The Data Explorer is an integration of Azure Data Explorer directly into PlayFab's GameManager. There is a "basic" tab, which gives you a basic UI to do some analytics. If you want to go deeper, you can use the "advanced" tab, which lets you write your own queries using the SQL-like Kusto Query Language (abbreviated as "KQL"). You can also export the raw event data, either periodically (Event Export) or continuously (Data Connections) to use the data in other analytics systems of your choice.

If you want to learn KQL, here's a fun way to learn it - the Kusto Detective Agency!

Automation

You may use PlayFab's Automation functionality to react to PlayStream Events. Without writing additional code, you can use PlayFab's Rules to react to events. Just specify the event type you invented while creating the event, and set up conditions and actions. For example, you might want to send a welcome Email once a player registered for your game:

You might as well use use CloudScript Functions to trigger backend code execution via Azure Functions to be even more flexible To achieve that, you can set up a Rule in PlayFab to run an Azure Function if a specific event is appearing in the PlayStream. Check out my in-depth walk-through on how to do this - or have a look at our example project, where we used PlayStream to implement a Match History!

Conclusion

In this post, I showed you the differences of the legacy and the new Events API and why you should use the Events API going forward to reduce cost and overhead and enabling you to write Telemetry events, which can further lower your cost.

You als o got a glimpse of the possibilities of PlayFab's built-in analytics capabilities and how you can use PlayStream events to react to them in near-realtime.