Metrics Interface

Interface to record play sessions for game usage data collection.

3 mins to read

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. To access the Game Analytics dashboard, sign in to the Developer Portal at dev.epicgames.com/portal, and select Analytics in the left-hand navigation.

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 does 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_EndPlayerSessionOptions data structure to mark the end of the session.

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

PropertyValue
ApiVersionSet this to EOS_METRICS_BEGINPLAYERSESSION_API_LATEST.
LocalUserIdThe globally unique account identifier for the local user. Used for Epic user accounts.
LocalUserIdExternalThe globally unique account identifier for the local user. Used for non-Epic user accounts.
DisplayNameThe player's in-game name, as a UTF-8 string.
ControllerTypeThe type of game controller that the player is using.
ServerIpIP address of the game server hosting the game session.
GameSessionIdThe 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:

PropertyValue
ApiVersionSet this to EOS_METRICS_ENDPLAYERSESSION_API_LATEST.
LocalUserIdThe account ID of the player who started the session. This should match the LocalUserId used in the earlier call to EOS_Metrics_BeginPlayerSession.
LocalUserIdExternalThe 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.