ゲームの統計情報

ゲームの統計情報は、ゲームに関する累積統計情報です。プレーヤーは、ゲーマー プロフィールで確認できます。これらの統計情報により、プレーヤーは生涯の進捗状況を追跡したり、ハイライト シーンを確認したり、他のプレーヤーと比較したりできます。また、今後、クエストやソーシャル チャレンジなどの Google Play の機能を強化することもできます。

統合の手順

Game Stats API を使用して、繰り返し発生する統計情報には柔軟なプレーヤー イベントとして、進行状況の統計情報には事前定義されたイベント progressUpdate としてデータを送信します。また、ゲーマー プロフィールに表示される統計情報の計算ロジックと、その表示情報も構成する必要があります。

プレーヤー イベントは、ゲーム内の個別の瞬間、ゲームループの完了、進行状況のマイルストーンを表します。

プレーヤー イベントは次のように定義され、モデル化されます。

1. イベントは、試合の完了、ランニングの終了、宝箱のロック解除、エリアでの進行状況の保存など、プレーヤーが実行した特定のアクションで表されます。
2. 各アクションには、特定の結果またはアクションを定義する特定の特性があります。これらは、イベントとその特定の結果に関するコンテキストを提供するイベント プロパティとしてモデル化されます（たとえば、マッチタイプ、そのラン中に収集されたコイン、マッチの結果、ヘッドショット数など）。

統合は次の手順で構成されます。

• 未加工のデータスキーマを宣言する: Google Play Console で CSV アップロードを使用してプレーヤー イベントを定義します。CSV ファイルのガイドラインをご覧ください。
• Game Stats API と統合する: 柔軟なプレーヤー イベントと progressUpdate イベントについて、宣言された形式でプレーヤーの生データを送信します。
  • クライアントサイドまたはサーバーサイドの統合を使用して、定義されたすべてのイベントを送信します。詳細については、柔軟なイベントと progressUpdate イベントの例をご覧ください。
• ZIP ファイルをアップロードする: 3 つの CSV ファイルと、5 つの繰り返し統計と 1 つのプレーヤー進行レベルを定義するすべてのアイコン画像ファイルを提供します。詳しくは、ZIP ファイルのガイドラインをご覧ください。以下の情報も伝えてください。
  • 繰り返し統計情報の CSV ファイル:
    • 統計情報の一意の ID。
    • 統計情報の計算に使用するイベントラベルを指定します。ここでは progressUpdate イベントラベルは使用できません。
      • 統計情報の計算に使用するプロパティ ラベルを指定します。これは、指定されたイベントのプロパティである必要があります。
      • 集計タイプ（SUM、MAX、MIN、COUNT）を指定して、選択したプロパティ ラベルの統計情報を計算する方法を決定します。
      • 条件が満たされた場合にのみロジックを計算する省略可能なフィルタ条件を指定します。プロパティとイベントラベル、演算子（=、<、>）、しきい値を定義します。
    • 統計情報を競合機能に使用できるかどうかを示すブール値のフラグを含めます。
    • この機能が競合機能に使用できる場合は、正規のプレーヤーの 1 時間あたりの最小限度と最大限度。これは、リーグやソーシャル チャレンジなどの機能に参加しているプレイヤーが不正行為を行っている可能性があるかどうかを特定するために使用されます。
    • プレーヤーに表示される統計情報に一意の表示名を指定します。
    • 統計情報を説明する独自のテキストを提供します。この説明では、プレーヤーがどのようにして統計情報を獲得したかについて詳しく説明する必要があります。
    • CSV ファイルにアイコンの正確なファイル名を入力して、統計情報を表す一意のアイコンを指定します。
    • シーケンスの順序を指定して、ゲーマー プロフィールでプレーヤーに表示される統計情報の順序を指定します
    • 値の増加または減少がプレーヤーにとって良いかどうかを示す入力（省略可）を指定します。この入力は、プレーヤーの動きを祝うために使用されます。
    • 統計情報の単位（km、マイル、秒など）を指定します（省略可）。
  • プレーヤーの進行状況の統計情報の CSV ファイル:
    • プレーヤーに表示されるプレーヤーの進行状況に一意の表示名を指定します。
    • 統計情報を表す一意のアイコンを指定します。
    • 進行状況の統計の説明を入力します。
    • 値の増加と減少のどちらがプレイヤーにとって有利かを示すオプションの入力を指定します。この入力は、currentProgress プロパティの型が INT の場合にのみ、プレーヤーの動きを祝うために使用されます。
    • 統計情報の測定単位（km、マイル、秒など）を任意で指定します。
  • ローカライズ用の CSV ファイル: すべての統計情報のローカライズされた表示名を指定します。
    • ローカライズごとに 1 行を追加します。
    • 前の CSV で追加した統計情報の表示名文字列を使用して、ローカライズが追加される統計情報を一意に識別します。
    • 言語コードのリストから言語を指定します。
    • 指定された言語の表示名のローカライズを追加します。
    • 指定された言語での統計情報の説明のローカライズを追加します。

イベントの CSV ファイルのガイドライン

PlayerGameEvent.csv ファイルを使用してイベントをインポートできます。

PlayerGameEvent.csv 形式

CSV には、宣言されたイベントとそのプロパティがカンマ区切り値として次の順序で含まれています。

 Event Name,Property Name,Property Type

progressionStat の progressUpdate イベントを送信する場合は、このイベントの行を追加します。このイベントには、INT 型または STRING 型の currentProgress プロパティと、送信するその他のプロパティを少なくとも 1 つ含める必要があります。

統計情報の ZIP ファイルに関するガイドライン

ZIP ファイルを使用して統計情報を一度にインポートできます。ZIP ファイルで使用する正確なファイル名については、以下の表をご覧ください。

RepetitiveStatsConfig.csv 形式

CSV には、宣言されたイベントとそのプロパティがカンマ区切り値として次の順序で含まれています。

Stat ID, Event Name,    Property Name,  Aggregation,     Stat Display Name, Stat Description, Filter Property,  Filter Operator,    Filter Value,   Is Competitive, minLimit, maxLimit, Icon File Name, Sequence Number, Good value direction, unit

フィルタ条件を使用しない場合は、セルを空白のままにします。

ProgressionStatConfig.csv 形式

CSV には、宣言されたイベントとそのプロパティがカンマ区切り値として次の順序で含まれています。

Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit

進行状況の統計情報は、ゲーマー プロフィールの最初の統計情報としてプレーヤーに表示されます。

StatLocalizations.csv 形式

CSV には、宣言されたイベントとそのプロパティがカンマ区切り値として次の順序で含まれています。

Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description

スキーマを計画する

Game Stats API を使用して送信できるデータには、柔軟なプレーヤー イベントと、プレーヤーの進行状況の統計情報に関する事前定義済みイベントの 2 種類があります。次の例は、さまざまなゲームタイプでフレキシブル イベントがどのように表示されるかを示しています。

柔軟なプレーヤー イベント

プレーヤー イベントは、ゲーム内の特定の瞬間、ゲームループの完了、進行状況のマイルストーンによって定義されます。

• イベントを定義します。イベントとは、ゲーム内の特定の瞬間、ゲームループの完了、進行状況のマイルストーンのことです。
  • ゲームループの完了（対戦やランの完了など）。
  • 進行状況のマイルストーン（保存されたエリアの探索の進捗状況やクリアしたレベルなど）。
• プロパティを追加して、イベントとその結果に関するコンテキスト（レベル番号、マッチタイプ、武器の種類、武器の数、ヘッドショット、収集したコイン、マッチの結果、ラップタイム、車の種類など）を提供します。
• ゲームプレイ セッション内でイベントが発生したらすぐにイベントを送信します。たとえば、ループが完了した直後にゲームループ完了イベントを送信します。

progressUpdate イベント

ゲームにメインの進行メカニズムがある場合は、このイベントを使用して、プレーヤーの現在の進行状況を送信します。イベントには、INT または STRING 型の「currentProgress」という名前の事前定義されたプロパティが 1 つあります。このプロパティを使用して現在の進行状況の値を送信します。この値は、ゲーマー プロフィールのゲーム統計 UI に表示される唯一の値です。

プレーヤーはゲーム内の現在の進行状況でプロフィールを比較できるため、初回統合後に現在の進行状況の値を取得する際に遅延が発生しないことが重要です。プレーヤーに正確な現在の進行状況を伝えるため、各ゲーム セッションの開始時と、現在の進行状況が更新されるたびに progressUpdate イベントを送信する必要があります。

統合の詳細

API エンドポイントと SDK は早期フィードバックにご利用いただけます。2026 年 7 月より一般提供（GA）を開始する予定です。タイムラインを参照してください

このセクションでは、クライアントサイドとサーバーサイドの両方の統合でイベントを構築して送信する方法について説明します。

データを送信するタイミング

フレキシブル イベントは、ゲームループの完了や特定のゲーム内モーメントに関連するゲーム内アクションを表します。これらのイベントは発生したらすぐに送信してください。たとえば、ループが完了したらすぐにゲームループ完了イベントを送信します。

progressUpdate イベントは、プレーヤーの現在の進行レベルを表します。進行状況の統計情報は、次の状況でこのイベントを使用して送信する必要があります。

1. 現在の進行状況が更新されるたびに、最新の値をすぐに送信します。
2. プレーヤーがゲームを起動するたび。これにより、プレーヤーのこの統計情報が常に存在することが保証されます。

統合の手順

統合には、クライアントとサーバー間の 2 つのパスがあります。

サーバー間統合

公開 API エンドポイントを使用すると、次の構成を使用してリクエスト ペイロードでイベントを送信できます。

パスパラメータ

認可と認証

サーバー間 API 呼び出しは、OAuth 2.0 を使用した Play ゲームサービスへのサーバーサイド アクセスの標準ガイドラインに沿って行われます。リクエストには、https://www.googleapis.com/auth/games スコープで承認された Bearer トークンを含める必要があります。

Flexible Events: リクエスト本文

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
"timestampValue": "string",
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

progressUpdate イベント: リクエストの本文

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent - progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string
}

レスポンスの本文

成功した場合、空の JSON オブジェクトとともに HTTP 200 OK ステータスを返します。

リクエスト本文の例

柔軟なイベント: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication //and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "survivalTimeSeconds": {
          "durationValue": "240s"
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate イベント

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

クライアントサイドの統合

クライアントサイドの統合は、Unity、Java、C++ の各 SDK を使用して利用できるようになります。

PlayerGameEvent のクライアントサイド統合では、SDK に応じて Java または Csharp でトリガー ポイントにイベント オブジェクトを構築し、SDK で提供されるアップロード関数を使用して送信します。

同様に、progressUpdate イベントでは、currentProgress プロパティと追加の定義済みプロパティを使用して更新された進行状況を記録し、SDK が提供するアップロード関数を使用して送信します。

イベント

PlayerGameEvent のクライアントサイドの統合は次のとおりです。

Flexible Player Game Event をビルドする

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("matchCompleted")
  .addProperty("matchId", "Match_A")
  .addProperty("gameMode", "Battle_B")
  .addProperty("mapId", "Location_XYZ")
  .addProperty("isWinner", true)
  .addProperty("survivalTimeSeconds", "240s")
  .addProperty("playerElimination", 2)
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var playerEvent = new PlayerGameEvent.Builder("matchCompleted")
   .AddProperty("matchId", "Match_A")
   .AddProperty("gameMode", "Battle_B")
   .AddProperty("mapId", "Location_XYZ")
   .AddProperty("isWinner", true)
   .AddProperty("survivalTimeSeconds", "240s")
   .AddProperty("playerElimination", 2)
   .Build();
var events = new List();
// ... populate list ...

// Build the PlayerGameEvent
PgsPlayerGameEvent* player_event = PgsPlayerGameEvent_create("matchCompleted");
if (player_event != nullptr) {
   PgsPlayerGameEvent_putString(player_event, "matchId", "Match_A");
   PgsPlayerGameEvent_putString(player_event, "gameMode", "Battle_B");
   PgsPlayerGameEvent_putString(player_event, "mapId", "Location_XYZ");
   PgsPlayerGameEvent_putBoolean(player_event, "isWinner", true);
   PgsPlayerGameEvent_putString(player_event, "survivalTimeSeconds", "240s");
   PgsPlayerGameEvent_putLong(player_event, "playerElimination", 2);
}

progressUpdate プレーヤー ゲームイベントをビルドする

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
  .addProperty("currentProgress", 52)
  // Add other properties if needed
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
   .AddProperty("currentProgress", 52)
   // Add other properties if needed
   .Build();
var events = new List();
// ... populate list ...

PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
   PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}

Record Event And Upload

// Buffers the event locally.
client.recordEvent(event);

// Buffers the events locally, (List version)
client.recordEvents(events);

// This submits the events to PGS
client.requestEventsUpload();

// Buffers the event locally.
PlayGamesPlatform.Instance.RecordEvent(playerEvent);

// Buffers the events locally, (List version)
PlayGamesPlatform.Instance.RecordEvents(events);

// This submits the events to PGS
PlayGamesPlatform.Instance.RequestEventsUpload();

// Record the event
PgsGameStatsClient_recordEvent(client, player_event);

// This submits the events to PGS
PgsGameStatsClient_requestEventsUpload(client);

// Clean up handle to avoid leaks
PgsPlayerGameEvent_destroy(player_event);

// Clean up client handle when PGS operations are finished
PgsGameStatsClient_destroy(client);

タイムライン