Understand players with analytics events

Events are the behavioral signal Satori uses to build player profiles, compute properties, and populate every metric, report, and audience in your project.

How events flow through Satori #

When your game fires an event, Satori records it against the player’s identity and immediately runs it through the event pipeline. This triggers two things:

• Computed properties: Satori generates or updates a set of properties on the identity based on the event (count, timestamps, values). These properties feed your audience filter expressions and segmentation.
• Metrics and reports: Events feed directly into the performance monitoring surfaces: the dashboard, retention reports, RoAS calculations, and any custom metrics you define.

If an event isn’t fired, it doesn’t exist in Satori, and any downstream feature that depends on it will be incomplete or empty.

View event history per player #

Every event your game fires is recorded against the player’s identity and visible in the Events tab on the identity detail view. Use this to confirm that a specific player’s event history is in the expected state, or to debug missing computed properties and empty audiences.

Open any event to see full event details, value, and metadata.

Event types #

Satori recognizes three types of events.

Core events #

Core events are predefined by Satori and can’t be modified or deleted. They represent standard player behaviors that Satori’s built-in audiences, computed properties, and monitoring features depend on.

The following core events are commonly used across monitoring, segmentation, and experiments. A series of computed properties are automatically generated and tracked per identity for each of these default events, as long as the event is fired.

Synthetic events #

Synthetic events, also known as server-side events, are automatically generated and tracked by Satori in response to certain actions. For example, Satori fires _propertiesUpdate whenever a player’s properties change, whether from a client SDK call or during authentication. You don’t need to instrument these.

User-defined events #

User-defined events are events you create for game-specific behaviors that core events don’t cover, such as questCompleted, achievementUnlocked, or offerViewed. Like core events, user-defined events must be fired explicitly by your game client. Create and manage them in Taxonomy > Events tab in the console.

Define a custom event in the Satori console before your client sends it. The event name you register here is what your metrics will reference and what your client code must send exactly.

Define valid events #

In the Taxonomy page of the console, the Events tab displays the complete list of events that must be accepted by Satori from clients. It describes the list of valid event schemas.

From here you can delete existing events, or create new ones. Note that Satori comes with a set of core events that can’t be modified or deleted.

Validate data with schema validators #

Every event’s value is checked against a schema to ensure your data remains reliable and consistent. Schema validators define the expected shape of an event’s value or metadata field, and Satori rejects any event that doesn’t match.

The Validators tab in the Taxonomy page displays the complete list of schema validators that Satori uses to validate data from Events, Feature Flags, Experiments, and Live Events.

Satori provides the following built‑in validators:

• ANY - Accepts any value; no validation.
• Number - Expects a numeric value.
• String - Expects a string.
• Object - Expects a JSON object (arbitrary keys/values allowed).
• Event‑Revenue‑Metadata - Specialized object for revenue events; include at least amount and currency (and optional test) to enable correct conversion and revenue calculations.

You can define your own validator. If an analytic event requires a specific payload shape, define the validator here first, then reference it when you create the event in the Events tab.

Debugger for invalid events #

If Satori receives events that aren’t declared in your taxonomy (i.e., an invalid event), it captures them in a temporary buffer. Open the Debugger tab to inspect what your game client is actually sending and use that to correct or extend your event schema.

Events may be rejected for any of the following reasons:

• INVALID_VALUE
• INVALID_METADATA
• VALUE_LENGTH_EXCEEDED
• METADATA_SIZE_EXCEEDED
• INVALID_NAME
• INVALID_ID
• INVALID_SCHEMA

Using metadata or value for custom data #

Satori events include two fields for custom data:

Example (tutorialCompleted):

1
2
3
4
5
6
7
8

{
  "name": "tutorialCompleted",
  "value": 3,
  "metadata": {
    "tutorialType": "movement",
    "isSkipped": false
  }
}

Send the event from the client #

Once the event is created, instrument your game client to send it when the relevant action occurs. The event name in your code must exactly match the name you registered in the console.

1
2

var session = await client.AuthenticateAsync("<playerId>");
await client.EventAsync(session, new Satori.Event("level_complete", DateTime.Now));

Satori begins computing metrics and updating audiences as events arrive. The event doesn’t need to reach a minimum threshold before you can create a metric against it.

For a step-by-step guide on how to use custom events to drive audience and experiments, see Experimenting with audiences.

Tracking players before sign-in #

When a player starts your game without signing in, Satori can still track their activity under a temporary identity (typically device-based). If that player later authenticates, Satori merges their guest history into their permanent identity.

Here’s what happens:

1. Player starts as guest: Your client calls Authenticate with a temporary ID. Satori fires _identityCreate and _sessionStart for this identity.
2. Player generates activity: All events, properties, and experiment assignments are tracked under the temporary identity.
3. Player signs in: Your client calls Identify with the player’s permanent ID. Satori fires _identify, migrates all data from the temporary identity to the permanent one, and deletes the temporary identity.

See Identifying a session with a new ID for more details.

Commonly confused terms #

Some Satori terms sound similar but have distinct meanings. The following clarifies what each one means.

itemSpent vs itemConsumed #

Use the item events to distinguish cost from use:

See also #

• How to Send Server-Side Analytic Events
• How to use Satori for Effective Session Management