Progression Snapshot Interface
The Progression Snapshot Interface allows storing player-specific game data for the purposes of supporting an end-user experience for Epic account merging. As of today, the concept of merging two separate Epic accounts, owned by the same user, into a single Epic account does not exist. However, this type of account merging is a feature that will be made available to users of Epic Accounts in the future.
The progression snapshot feature becomes relevant for users in cases where they have two separate Epic accounts, and have played the same game on both of the accounts. In such a case, if the user chooses to merge their Epic accounts into a single account, the Epic overlay will be able to present a snapshot view of their game progress for both accounts. This allows users to choose their preferred game progression to preserve as a result of the account merge operation.
Account merging is relevant for users who have created a new frictionless Epic "proxy" account within in-game context outside of the Epic Games Store, while already having another existing Epic account.
Merging of an in-game created Epic "proxy" account into another existing Epic account will allow users to unify their social graph, ecom entitlements, linked accounts and other account information.
Specifics and limitations of Epic account merging and the user experience will be made through new documentation closer to making the operation available to end-users. For now, games will be able to start recording progression snapshots ahead of time in preparation to better support users who may go through the account merge and have conflicting game progressions on both accounts.
Usage of the Progression Snapshot
Progression Snapshots provide means for developers to record relevant game progression data with the Epic Online Services backend as the game is played. This information, in the form of key-value pairs, provides context for users that may need to merge accounts in a cross-progression environment. Users will be able to compare the game progress made using both accounts side-by-side, and choose the preferred progression to keep.
Mockup design of the end-user experience subject to change. Progression snapshot data is presented to the user as part of the Epic account merging process within the in-game Epic overlay experience.
As the key-value pairs are stored as-is on the backend, the game is responsible for any localization of the stored data, if needed.
We recommend using easy to understand key-value pairs such as "Character Level: 10". The game could also calculate a total progression value based on different variables, such as "Game Completion: 72%".
Selected Account ID
The progression snapshot and user choice at the time of an account merge is application-scoped. This allows users to make the game progression selection for each game separately, with the introduction of a new Selected Epic account ID concept. This is a new Epic account identifier that will be set at login time to the Epic account ID the user chooses to use with the application. It is always set to the same value as the Epic account ID, or if the user has gone through an account merge operation and has had to make a selection, it is set to the Epic account ID that the application should use for all game-scoped data.
Storing a Game Progression Snapshot For Users
Progression snapshots for the local user should be sent to the backend once per game session. The recommended times to do so are when the local user has been logged in and their current game state successfully loaded and whenever the user makes significant progress in the game (e.g. level up, match played, stage completed, etc.).
Updating the progression snapshot will always fully overwrite any previously stored snapshot. For example, if a previous snapshot contained 4 key-value pairs and a new snapshot includes only 3, the result snapshot will contain the 3 key-value pairs that the snapshot was updated with.
Creating the initial progression snapshot, or updating an already existing snapshot follows the same application code flow. First a local snapshot state is initialized using the EOS_ProgressionSnapshot_BeginSnapshot API and passing in the local user’s EOS_ProductUserId in the EOS_ProgressionSnapshot_BeginSnapshotOptions structure.
Then key-value pairs representing the game state are added as the snapshot data using the EOS_ProgressionSnapshot_AddProgressionOptions API, passing the SnapshotId and the key-value pairs in the EOS_ProgressionSnapshot_AddProgressionOptions structure. This API must be called once per key-value pair that should be added to the progression snapshot. The order in which key-value pairs are added to the snapshot are ultimately the order in which they will be presented to the user in the Epic overlay. Make sure to pass the most important information first to help users more quickly identify the progression they are interested in.
After filling in the complete snapshot data, upload the collected snapshot to the backend using the EOS_ProgressionSnapshot_SubmitSnapshot API, passing the SnapshotId in the EOS_ProgressionSnapshot_SubmitSnapshotOptions structure.
Finally, release internal memory resources allocated by the SDK using the EOS_ProgressionSnapshot_EndSnapshot API, passing the SnapshotId in the EOS_ProgressionSnapshot_EndSnapshotOptions structure.
Deleting Game Progression Snapshot For Users
It is not necessary to delete any previously stored progression snapshot before updating it with a newer state. However, if you need to delete the progression snapshot for integration testing purposes or otherwise, the game client may do so for the local logged in user.
To delete the stored progression snapshot for a local logged in user, use the EOS_ProgressionSnapshot_DeleteSnapshot API, passing the EOS_ProductUserId in the EOS_ProgressionSnapshot_DeleteSnapshotOptions structure.
If the backend data was successfully deleted, the CompletionDelegate passed in by the application will return an EOS_EResult::EOS_Success result status. If no progression snapshot data existed for the user, EOS_EResult::EOS_NotFound is returned.