Progression Snapshot Interface

进度快照接口允许存储玩家相关的游戏数据，以便支持Epic 账号 合并相关的最终用户体验。目前，还无法将同一用户拥有的两个独立的Epic账号合并为一个Epic账号。但将来我们会向Epic账号的用户提供此类账号的合并功能。

如果用户拥有两个独立的Epic账号，并且在两个账号上都玩过相同的游戏，进度快照功能就会成为用户必不可少的实用功能。在这种情况下，如果用户选择将Epic账号合并为一个账号，Epic覆层将可以显示两个账号的游戏进程快照视图。这样用户就可以选择他们想用的游戏进度，并通过账号合并操作来保存进度。

开发人员可以利用进度快照在玩游戏时使用Epic在线服务后端来记录相关游戏进度数据。此信息采用键值对的形式，可为需要在跨进度环境中合并账号的用户提供上下文。用户将能够并排比较两个账号的游戏进度，然后选择要保留的进度。

最终用户体验的模型设计可能会发生变化。进度快照数据作为Epic账号合并过程的一部分，会在游戏内Epic覆层体验中呈现给用户。

账号合并时的进度快照和用户选择是应用程序作用域内的操作。这就允许用户分别为每个游戏进行游戏进度选择，并引入新的 已选Epic账号ID 的概念。这是一个新的Epic账号辨识符，将在登录时设置为用户选择在应用程序中使用的Epic账号ID。它始终设置为与Epic账号ID相同的值，如果用户已完成账号合并操作并做出了选择，则将其设置为应用程序应该应用于所有游戏作用域内数据的Epic账号ID。

本地用户的进度快照应在每个游戏会话中向后端发送一次。建议采取该操作的时间是本地用户已登录并成功加载当前游戏状态时，以及用户在游戏中取得重要进展时（例如升级、完成比赛、完成关卡等）。

更新进度快照将始终完全覆盖所有以前存储的快照。例如，如果之前的快照包含4个键值对，而新快照仅包含3个，则最终的快照将包含更新快照时使用的3个键值对。

创建初始进度快照或更新现有快照将使用相同的应用程序代码流。首先使用 EOS_ProgressionSnapshot_BeginSnapshot API对本地快照状态进行初始化操作，将本地用户的 EOS_ProductUserId 传入 EOS_ProgressionSnapshot_BeginSnapshotOptions 结构体。

然后使用 EOS_ProgressionSnapshot_AddProgressionOptions API将代表游戏状态的键值对添加为快照数据，将 SnapshotId 和键值对传入 EOS_ProgressionSnapshot_AddProgressionOptions 结构体。每个应添加到进度快照的键值对都必须调用一次此API。键值对添加到快照的顺序，就是最终在Epic覆层中呈现给用户的顺序。确保首先传递最重要的信息，以帮助用户更快地确定需要的进度。

填写完整的快照数据后，使用 EOS_ProgressionSnapshot_SubmitSnapshot API将采集到的快照上传到后端，传入 EOS_ProgressionSnapshot_SubmitSnapshotOptions 结构体中的 SnapshotId 。

最后，使用 EOS_ProgressionSnapshot_EndSnapshot API释放SDK分配的内存资源，传入 EOS_ProgressionSnapshot_EndSnapshotOptions 结构体中的 SnapshotId。

使用新的状态更新进度快照之前，不需要删除之前存储的进度快照。但如果出于集成测试目的或其他目的需要删除进度快照，游戏客户端可以为本地登录用户执行此操作。

要删除为本地登录用户存储的进度快照，应使用 EOS_ProgressionSnapshot_DeleteSnapshot API，传入 EOS_ProgressionSnapshot_DeleteSnapshotOptions 结构体中的 EOS_ProductUserId。

如果后端数据删除成功，应用程序传入的 CompletionDelegate 会返回 EOS_EResult::EOS_Success 结果状态。如果用户的进度快照数据不存在，则返回 EOS_EResult::EOS_NotFound。