Sessions

A session is a bounded time window during which a player is considered active. Satori defines a session as the time window from the first creation of the session (authentication of the player to Satori) to their last event in this session. Hence, sessions in Satori represent continuous periods of player activity and are important to understanding user behavior within a session by linking multiple events to the same session, calculating metrics like session duration, session count, and total play time.

With Satori Sessions and implementing suggested session tracking methods, you can:

  • Accurately track player engagement across different systems.
  • Associate player events with correct gameplay sessions.
  • Support consistent analytics even when data originates from server processes or background tasks.

This document describes how sessions are tracked, limitations with server-side sources, and strategies for unifying these models in the future.

Key Terminology #

  • Session: A defined period during which a player is actively engaged.
  • Session ID: A unique identifier automatically generated for each active session.
  • Identity: A unique user profile linking events to specific players.
  • Client SDKs: Libraries (e.g., Unity SDK) that handle session lifecycle automatically.
  • Orphaned Events: Events without session information typically originating from server-side or background processes.

Session Creation #

Satori provides flexible options to create a session for a player:

  • Using Client SDKs: You can start a user session using the Client SDK’s AuthenticateAsync function.
  • Using Nakama: You can also start a user session in Satori using Nakama’s Server Framework Satori Authenticate function.

Scenario 1: Nakama ✅ | Satori Client SDK ✅
Analytic events are sent both by Nakama and Satori Client.

  • Authenticate users via the client.
  • Configure Nakama with no_session = true.
  • Nakama events will be associated with the most relevant client session seamlessly.

Scenario 2: Nakama ✅ | Satori Client SDK ❌
Analytic events are sent only by Nakama.

  • Configure Nakama with no_session = false.
  • Nakama-generated authentication will create an identity session in Satori and subsequent analytics events associate with the latest Nakama-created session.

Scenario 3: Nakama ❌ | Satori Client SDK ✅
Analytic events are sent only by Satori Client.

  • Authenticate users via your client.
  • Analytic events are solely sent through the Client SDK.

Session Management #

When a new session is created, Satori will return a session object containing:

  • Session Token and Expire Time
  • Refresh Token and Expire Time

Both session and refresh token expiry can be configured. Their default values are:

  • session_token_expiry_sec: 129600 seconds (1.5 days)
  • session_refresh_token_expiry_sec: 604800 seconds (7 days)

The session will be active until the session token expiry time; you can extend the session up to the refresh token expiry time. Unless you have a special use case, reusing the same session and extending it may lead to inaccurate session metrics such as “Session Count” and “Session Duration”. In order to track those metrics more consistently, we suggest you manage your sessions with following steps:

  1. Authenticate the player every time your players open your game. For mobile games, you may prefer to use the same session if the operating system allows the game to continue. This can be useful for cases when the player receives a call or switches to another application briefly. For cases when the player has not returned to the game for a longer time, it is better to re-authenticate instead of refreshing the session.
  2. Avoid using refresh token if it is not necessary for your use case.
  3. Set up your session token and refresh token expiry configs based on your game’s specific needs.
  4. If you are using Nakama or any other server (such as headless servers) to send events, use the Server Event API to send events without a session ID. Satori will automatically link to the most recent session if it is reported close enough. Using this method, your server messages will not be tied to another session, which may cause duplication in session count and duration.
For Better Session Metrics

If the player opened the game for 5 times and played 60 minutes in total, the correct metrics is to have “Session Count” as 5 and “Avg. Session Duration” as 12 minutes. However, if you extend the same session id, it may result in having only 1 session count with 60 minutes of “Avg. Session Duration”. To have correct metrics:

  • Always perform a Satori authenticate every time your players open the game.
  • Do not try to use the same session by extending it if you do not have a special use case. Instead, re-authenticate to create a new session.
  • Use correct event sending methods especially if you have both client- and server-triggered events.

Handling Missing Session IDs #

When events are received without session IDs, Satori automatically associates these with the latest valid session if:

  • The latest session is within the defined validity window.
  • Events without valid sessions remain unlinked (orphaned) but are still logged.

A new configurable grace-period parameter named event.sessionless_events_grace_period_sec (default is 1800 seconds) helps ensure late-arriving events can still be attributed to recent sessions, improving analytics accuracy.

Session Metrics #

Satori offers the following default metrics for capturing session data:

  • Session Count
  • Session Length
  • Average Session Length

You can view these metrics from both the Metrics and Explore pages.

In addition, the Retention Reports page provides additional session metrics for both all players and selected cohorts. These metrics are:

  • Session Count
  • Average Session Duration
  • Average Playtime

If you would like to dive deeper or start implementing session-aware analytics in Satori, check out the following resources: