Dependencies

• At least one defined player experiment - If you haven't defined an experiment yet, see Working with Experiments to get started.
• Have the relevant analytics event and corresponding event sinks implemented - Check out Implementing Analytics Events in Game Logic for instructions on how to implement the Events.

Key Concepts

• Analytics ID is an opaque string label used for identifying some property.
• Experiment Analytics ID is the analytics label that identifies a specific Experiment.
• Variant Analytics ID is the analytics label for the Variant Group of the Experiment a player is in.
• Control Group Analytics ID is the analytics label to be used in place of a Variant Analytics ID if a player was placed into the control group.
• Analytics Data Processing Pipeline is an external system or a service that uses Analytics Events to produce various metrics, for example Firebase Analytics.

Identifying Experiments in Analytics Events

For an Analytics Data Processing Pipeline to be able to produce Experiment and Variant specific results, it needs to identify which Player Analytics Events correspond to which Experiment and which Variant. In Metaplay, this is identification handled with the use use of Analytics IDs. Each Experiment and Variant (including the Control Group) has an associated Analytics ID which is an opaque string value defined in Game Config. Then, each emitted Event from a player is labeled using these IDs. As players may be assigned into multiple active Experiments, a Player's Analytics Labels are essentially a list of (ExperimentAnalyticsId, VariantAnalyticsId | ControlGroupAnalyticsId) pairs. The Analytics Pipeline may then use these event labels to classify events for per-experiment-variant results.

For server-side events that use the built-in sinks, these labels are added automatically to the emitted event, in the context field as described in Streaming Analytics Events to External Storage. For client-side sinks or custom server side sinks however, the developer needs to manually integrate the labeling of event. This process is described in this document.

Decoupled IDs

In the source data, the Experiment Analytics ID and Experiment ID are intentionally decoupled. While the Experiment IDs identify a certain experiment run and hence should not be reused for later experiment runs, there is no such limitation for Analytics IDs. In advanced usage scenarios, an experiment could be repeated multiple times by having each run have a different Experiment ID while sharing the _Experiment Analytics ID_s.

Client-Side Analytics Events

For Client-side analytics services, such as when using Firebase Analytics, the active Analytics ID labels must be included in the events manually. On Unity client, the set of Experiment and their Analytics IDs are provided via MetaplaySDK.ActiveExperiments. The dictionary contains the set of currently active Experiment and their Analytics IDs and is it updated by the time the Connection State becomes Connected.

For example for Firebase Analytics, we could run the following code to label all events with the active Experiments. Since the Connected happens only some time after the application launch, we have added a todo to defer firing events until the labels are set. Note that a proper implementation should also handle the case where Connected is not reached within a reasonable time.

OnConnected() // called somewhere when Connection Status becomes Connected
{

// Assign player ID for cross-referencing ids later on
Firebase.Analytics.FirebaseAnalytics.SetUserId(PlayerModel.PlayerId.ToString());

// Assign experiment labels
foreach (ExperimentMembershipStatus membership in MetaplaySDK.ActiveExperiments.Values)
{
    // Set labels directly as <ExperimentID> = <VariantID>
    // Note that other labelling strategies exist
    Firebase.Analytics.FirebaseAnalytics.SetUserProperty(membership.ExperimentAnalyticsId.ToString(), membership.VariantAnalyticsId.ToString());
}

<!-- markdownlint-disable-next-line MPL006 -->
// \todo: If we have some deferred events that were emitted before session started in
//        order to wait for the labels to resolve, flush them now.

The currently active experiments of a player are shown in the MetaplaySDKBehavior Inspector.

BotClient Support

On BotClient Testing, the ActiveExperiments is also directly available in the actor context and is similarly set upon successful connection. This can be used to test client-side analytics.

Server-Side Custom Analytics Events

For sending events into a custom sink from the server side, we recommend implementing a custom Analytics Event Sink as described in BigQuery Analytics Event Format

However, if the active Experiments and their IDs need to be accessed from the server code, you can use the ActiveExperiments dictionary which is directly available in the actor context. It is updated just before the session starts and hence may be accessed in the session start callback and the handlers. Note that these values are intended for informational use only. All Game Logic alterations that depend on Experiments should only use the Game Config and then vary the relevant value with the Experiment Variants.