Metrics Interface

Interface to record play sessions for game usage data collection.

The Metrics Interface tracks your game's usage and populates the Game Analytics dashboard in the Developer Portal. This data includes active, online instances of the game's client and server, and past sessions played by local players.

Collecting Usage Metrics

To enable data collection, acquire an EOS_HMetrics handle through the Platform Interface function, EOS_Platform_GetMetricsInterface. All Metrics Interface functions require this handle as their first parameter.

The Epic Online Services (EOS) SDK collects the data, while the backend service performs processing and storage. The aggregated results are available in the Game Analytics dashboard, enabling you to monitor worldwide game activity, player retention, and online user counts.

Limitations

Metrics data updates every five minutes. While testing, your client may not show up in the dashboard immediately due to this update frequency. In addition, because user retention calculation requires a few days of historical data, the Game Analytics dashboard will not show player retention information for the first several days.

Performing metrics collection requires using EOS SDK's exposed API exclusively. The EOS SDK may not be used for metrics collection with any outside program or service.

Reporting Play Sessions

EOS data collection relies on the game reporting when each player begins and ends each play session. To record a session, call EOS_Metrics_BeginPlayerSession with an EOS_Metrics_BeginPlayerSessionOptions data structure for each player in the game. This will notify the SDK that the player has joined a game on a remote server, or is hosting a game on their own. Once the player leaves the server or ends the local session, call EOS_Metrics_EndPlayerSession with an EOS_Metrics_BeginPlayerSessionOptions data structure to mark the end of the session.

When using the Metrics Interface, you must pair calls to EOS_Metrics_BeginPlayerSession with calls to EOS_MetricsEndPlayerSession. Failure to do so will cause inaccuracies in the reported metrics data. Making rapid calls to EOS_Metrics_BeginPlayerSession and EOS_Metrics_BeginPlayerSession can cause the backend service to discard your data.

When calling EOS_Metrics_BeginPlayerSession initialize the EOS_Metrics_BeginPlayerSessionOptions structure with the following information:

Property

Value

ApiVersion

Set this to EOS_METRICS_BEGINPLAYERSESSION_API_LATEST.

LocalUserId

The globally unique account identifier for the local user. Used for Epic user accounts.

LocalUserIdExternal

The globally unique account identifier for the local user. Used for non-Epic user accounts.

DisplayName

The player's in-game name, as a UTF-8 string.

ControllerType

The type of game controller that the player is using.

ServerIp

IP address of the game server hosting the game session.

GameSessionId

The game can set a custom match identifier string that will attach to the session record on the backend service. This data will be available in the future to associate game sessions with tracked events that occur during play.

When calling EOS_Metrics_EndPlayerSession initialize the EOS_Metrics_EndPlayerSessionOptions structure with the following information:

Property

Value

ApiVersion

Set this to EOS_METRICS_ENDPLAYERSESSION_API_LATEST.

LocalUserId

The account ID of the player who started the session. This should match the LocalUserId used in the earlier call to EOS_Metrics_BeginPlayerSession.

LocalUserIdExternal

The account ID of the player who started the session. This should match the LocalUserIdExternal used in the earlier call to EOS_Metrics_BeginPlayerSession.

Collecting Concurrent Online Users (CCU) and User Retention Data

The EOS SDK automatically records the number of concurrent online users and game servers. This functionality becomes active when the SDK initializes on any online machine running the game's client or server. User retention data is calculated once the game has been live for a few days, and uses historical data based on reported play sessions.