> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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` | プレイヤーが使用した ID プロバイダー (例: 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`

ゲーム セーブ バージョンが「既知の良好 (known good)」として明示的にマークされたときに発行されます。既知の良好なバージョンは、信頼できる復元ポイントとして機能します。プレイヤーやタイトルが不正なセーブ状態から回復する必要がある場合、システムがロールバックするバージョンです。

| フィールド | タイプ | 説明 |
| - | - | - |
| `Version` | `long` | 既知の良好としてマークされたバージョン |
| `MarkedAt` | `DateTime` | バージョンがマークされたときのタイムスタンプ |

***

## シナリオ

### シナリオ: 標準的なクロス デバイス使用

典型的なクロス デバイスのフローは、プレイヤーが 1 つのデバイスでセーブし、別のデバイスで再開するようなものです。PlayStream では、このパターンは `Version` 番号が増加する `gamesave_version_finalized` イベントの一連の流れとして表示されます。

**表示される内容:**

* プレイヤーがセーブするたびに `gamesave_version_finalized` イベントが表示され、`DeviceType` と `PlayerIdentityProvider` は使用されたデバイスと ID プロバイダーを示します。
* `NewFileCount` と `NewFilesSizeBytes` は、前のバージョンと比較してどれだけのデータが変更されたかを示します。`NewFileCount` が 0 のバージョンは、プレイヤーが新しいファイル コンテンツなしでバージョンを確定したことを意味します (たとえば、メタデータのみの更新)。
* 通常のセーブでは、`Conflict` は `null`、`IsGeneratedByRollback` は `false` です。

**注視すべき項目:**

* **プレイヤーごとのセーブ頻度**: 確定イベントの割合を追跡して、プレイヤーのエンゲージメントとセーブ動作を理解します。
* **時間の経過に伴うセーブ サイズ**: `TotalSizeBytes` と `NewFilesSizeBytes` を監視して、ストレージ コストや同期時間に影響する可能性のあるセーブ データの予期しない増加を検知します。
* **デバイス分布**: `DeviceType` を集約して、プレイヤーが最も頻繁にどのプラットフォームからセーブしているかを理解します。

### シナリオ: 競合解決

2 つのデバイスが同じベース バージョンに対してゲーム セーブ バージョンを確定するときに競合が発生します。たとえば、プレイヤーがコンソールと PC で同時にオフラインでプレイし、両方のデバイスがオンラインに戻ったときに同期しようとする場合などです。

**表示される内容:**

* 競合解決中、クライアントは常にローカル ファイルを新しいマニフェストにアップロードし、マニフェストを確定します。このプロセスにより、null でない `Conflict` オブジェクトを持つ単一の `gamesave_version_finalized` イベントが生成されます。既存のクラウド バージョン (以前のイベントで既に確定済み) は新しいイベントを生成しません。
* `Conflict.IsWinner` は、プレイヤーのローカルの変更が競合に勝ったかどうかを示します:
  * `true`—プレイヤーは **ローカルを保持** を選択しました。新しいマニフェストが正規のバージョンとなり、以前のクラウド バージョンは置き換えられます。
  * `false`—プレイヤーは **リモートを保持** を選択しました。新しいマニフェストは (拒否されたローカル データを含む) ロールバック ポイントとして保存され、既存のクラウド バージョンが正規のままとなります。
* `Conflict.ConflictingVersion` は、競合していた既存のクラウド バージョンを指します。

**注視すべき項目:**

* **競合率**—`Conflict` が存在する `gamesave_version_finalized` イベントをフィルターします。競合率の上昇は、プレイヤーが同期せずに頻繁にデバイスを切り替えていること、またはタイトルのセーブ頻度が不要なバージョン衝突を引き起こしていることを示す可能性があります。
* **ローカル対リモートの優先度**—`IsWinner = true` (ローカル保持) と `IsWinner = false` (リモート保持) の比率を比較して、プレイヤーが競合をどのように解決するかを理解します。片側への強い偏りは、競合プロンプトの UX 問題を示す可能性があります。
* **クロス デバイスの競合パターン**—競合イベントで `DeviceType` と `PlayerIdentityProvider` を使用して、どのプラットフォームの組み合わせが最も競合しやすいかを理解します。

### シナリオ: Known good とロールバック

「Known good」メカニズムを使用すると、特定のバージョンを信頼できる復元ポイントとしてマークできます。プレイヤーのセーブが破損したり回復が必要な場合、システムは最新の既知の良好なバージョンにロールバックし、そこから新しいバージョンを作成できます。

**表示される内容:**

* バージョンを復元ポイントとして指定すると、`Version` 番号と `MarkedAt` タイムスタンプを持つ `gamesave_version_marked_known_good` イベントが表示されます。
* ロールバックが発生した場合、システムは `IsGeneratedByRollback = true` の新しい `gamesave_version_finalized` イベントを発行します。この新しいバージョンのコンテンツは既知の良好なバージョンに基づいていますが、新しい増加したバージョン番号が付与されます。
* ロールバックが競合解決の一部としてトリガーされた場合、ロールバックによって生成されたバージョンにも `Conflict` データがある可能性があります。

**注視すべき項目:**

* **ロールバック頻度**—`IsGeneratedByRollback = true` の `gamesave_version_finalized` イベントを追跡します。タイトルで頻繁にロールバックが発生する場合、セーブの破損問題やタイトルのセーブ ロジックの問題を示す可能性があります。
* **既知の良好性の鮮度**—`gamesave_version_marked_known_good` の `Version` を、同じプレイヤーの最新の確定済み `Version` と比較します。大きなギャップは、ロールバックが必要な場合にプレイヤーが大きな進行状況を失うことを意味します。
* **ロールバックと競合の相関**—ロールバックによって生成されたバージョンが競合データと頻繁に一緒に表示される場合、そのパターンは、競合解決戦略が副作用としてロールバックをトリガーしていることを示唆する可能性があります。


## Related topics

- [PlayStream イベント モデル リファレンス](https://docs.xbox.com/ja-jp/services/playfab/api-references/events/index.md)
- [エンティティ イベントを使った PlayStream](https://docs.xbox.com/ja-jp/services/playfab/data-analytics/ingest-data/playstream-with-entity-events.md)
- [Custom Tag を使用してイベントをカスタマイズする](https://docs.xbox.com/ja-jp/services/playfab/data-analytics/ingest-data/playstream-custom-tags.md)
- [PlayStream とテレメトリを使用した統計情報](https://docs.xbox.com/ja-jp/services/playfab/player-progression/statistics/statistics-with-playstream-and-telemetry.md)
- [カスタム CloudScript の作成](https://docs.xbox.com/ja-jp/services/playfab/live-service-management/service-gateway/automation/cloudscript/writing-custom-cloudscript.md)