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:
| 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.