> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Saves PlayStream 事件

> PlayFab Game Saves PlayStream 事件的參考，涵蓋版本完成、衝突解決和已知良好回復的遙測欄位。

PlayFab Game Saves 會發出 PlayStream 事件，您可以使用這些事件追蹤玩家如何儲存、同步及管理其遊戲資料。使用這些事件監視存檔活動、偵測衝突，並了解玩家群中的跨裝置使用模式。

所有 Game Saves 事件都會針對 `playfab.gamesave` 命名空間中的 `title_player_account` 實體發出。

## 事件

### `gamesave_version_finalized`

每次完成遊戲存檔版本時發出。所有檔案都已上傳，且版本已完成。此事件是追蹤存檔活動的主要信號。

| 欄位 | 類型 | 描述 |
| - | - | - |
| `Version` | `long` | 已完成之遊戲存檔的版本號碼 |
| `FinalizedAt` | `DateTime` | 版本完成時的時間戳記 |
| `TotalSizeBytes` | `long` | 已完成版本的總大小，包括所有檔案 |
| `TotalFileCount` | `int` | 已完成版本中的檔案總數 |
| `NewFileCount` | `int` | 此版本中新增的檔案數目 |
| `NewFilesSizeBytes` | `long` | 此版本中新增之檔案的大小 |
| `PlayerIdentityProvider` | `string` | 玩家所使用的身分識別提供者 (例如 Steam、XBOX Live) |
| `DeviceType` | `string` | 上傳存檔之裝置的類型 |
| `IsGeneratedByRollback` | `bool` | 如果此版本是透過回復至先前版本所建立，則為 `true` |
| `Conflict` | `Conflict` | 當此版本是在衝突解決過程中完成時存在。否則為 `null`。請參閱[衝突解決](#scenario-conflict-resolution) |

**Conflict** (巢狀物件，只在衝突解決期間存在)：

| 欄位 | 類型 | 描述 |
| - | - | - |
| `IsWinner` | `bool` | 玩家的本機變更是否在衝突中勝出。此事件一律對應至從用戶端本機資料建立的新資訊清單。`true` 表示該資訊清單成為標準版本；`false` 表示該資訊清單被保留為回復點，而現有的雲端版本仍為標準版本 |
| `ConflictingVersion` | `long` | 發生衝突之現有雲端版本的版本號碼 |

### `gamesave_version_marked_known_good`

當遊戲存檔版本被明確標示為「已知良好」時發出。已知良好的版本可作為受信任的還原點。如果玩家或遊戲需要從不良的存檔狀態中復原，系統會回復至此版本。

| 欄位 | 類型 | 描述 |
| - | - | - |
| `Version` | `long` | 被標示為已知良好的版本 |
| `MarkedAt` | `DateTime` | 版本被標示時的時間戳記 |

***

## 案例

### 案例：標準跨裝置使用

典型的跨裝置流程看起來像是玩家在一部裝置上存檔，然後在另一部裝置上繼續。在 PlayStream 中，此模式會顯示為一系列 `Version` 號碼遞增的 `gamesave_version_finalized` 事件。

**您會看到：**

* 每次玩家存檔時都會有一個 `gamesave_version_finalized` 事件，其中 `DeviceType` 和 `PlayerIdentityProvider` 指出所使用的裝置和身分識別提供者。
* `NewFileCount` 和 `NewFilesSizeBytes` 顯示與先前版本相比變更了多少資料。`NewFileCount` 為 0 的版本表示玩家完成了沒有新檔案內容的版本 (例如僅限中繼資料的更新)。
* 對於正常存檔，`Conflict` 為 `null`，且 `IsGeneratedByRollback` 為 `false`。

**需要注意的事項：**

* **每位玩家的存檔頻率**：追蹤完成事件的速率，以了解玩家參與度和存檔行為。
* **存檔大小隨時間的變化**：監視 `TotalSizeBytes` 和 `NewFilesSizeBytes`，以發現存檔資料中可能影響儲存成本或同步時間的非預期成長。
* **裝置分佈**：彙總 `DeviceType`，以了解玩家最常從哪些平台存檔。

<a id="scenario-conflict-resolution" />

### 案例：衝突解決

當兩部裝置針對相同的基礎版本完成遊戲存檔版本時，就會發生衝突。例如，玩家可能同時在主機和 PC 上離線遊玩，而兩部裝置在恢復上線時都嘗試同步。

**您會看到：**

* 在衝突解決期間，用戶端一律會將其本機檔案上傳至新的資訊清單，並完成該資訊清單。此程序會產生單一 `gamesave_version_finalized` 事件，其中包含非 null 的 `Conflict` 物件。現有的雲端版本 (已在先前的事件中完成) 不會產生新事件。
* `Conflict.IsWinner` 會告訴您玩家的本機變更是否在衝突中勝出：
  * `true`——玩家選擇了**保留本機**。新的資訊清單成為標準版本，先前的雲端版本被取代。
  * `false`——玩家選擇了**保留遠端**。新的資訊清單被保留為回復點 (包含被拒絕的本機資料)，而現有的雲端版本仍為標準版本。
* `Conflict.ConflictingVersion` 指向發生衝突的現有雲端版本。

**需要注意的事項：**

* **衝突率**——篩選存在 `Conflict` 的 `gamesave_version_finalized` 事件。衝突率上升可能表示玩家經常在未同步的情況下切換裝置，或是您遊戲的存檔頻率造成不必要的版本衝突。
* **本機與遠端偏好**——比較 `IsWinner = true` (保留本機) 與 `IsWinner = false` (保留遠端) 的比例，以了解玩家如何解決衝突。強烈偏向某一方可能表示衝突提示有 UX 問題。
* **跨裝置衝突模式**——使用衝突事件上的 `DeviceType` 和 `PlayerIdentityProvider`，了解哪些平台組合最容易發生衝突。

### 案例：已知良好和回復

「已知良好」機制可讓您將特定版本標示為受信任的還原點。如果玩家的存檔損毀或需要復原，系統可以回復至最近的已知良好版本，並從中建立新版本。

**您會看到：**

* 當您將某個版本指定為還原點時，會有一個 `gamesave_version_marked_known_good` 事件，其中包含 `Version` 號碼和 `MarkedAt` 時間戳記。
* 如果發生回復，系統會發出新的 `gamesave_version_finalized` 事件，其中 `IsGeneratedByRollback = true`。此新版本的內容以已知良好版本為基礎，但會取得新的遞增版本號碼。
* 如果回復是在衝突解決過程中觸發的，回復產生的版本也可能包含 `Conflict` 資料。

**需要注意的事項：**

* **回復頻率**——追蹤 `IsGeneratedByRollback = true` 的 `gamesave_version_finalized` 事件。遊戲頻繁回復可能表示存檔損毀問題，或遊戲的存檔邏輯有問題。
* **已知良好的新鮮度**——將 `gamesave_version_marked_known_good` 中的 `Version` 與同一位玩家最新完成的 `Version` 進行比較。差距很大表示如果需要回復，玩家將會遺失大量進度。
* **回復與衝突的關聯**——如果回復產生的版本經常與衝突資料一起出現，此模式可能表示您的衝突解決策略會產生回復的副作用。


## Related topics

- [PlayStream 事件](/zh-TW/services/playfab/data-analytics/ingest-data/playstream-events.md)
- [PlayFab 的 PlayStream 事件模型參考](/zh-TW/services/playfab/api-references/events/index.md)
- [PlayStream 事件功能](/zh-TW/services/playfab/data-analytics/ingest-data/playstream-event-capabilities.md)
- [搭配實體事件使用 PlayStream](/zh-TW/services/playfab/data-analytics/ingest-data/playstream-with-entity-events.md)
- [撰寫自訂 CloudScript](/zh-TW/services/playfab/live-service-management/service-gateway/automation/cloudscript/writing-custom-cloudscript.md)