ゲームの統計情報

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

ゲームの統計情報は次の要件を満たしている必要があります。

• 購入（ジェムの購入など）を必要としない。つまり、IAP の購入の結果として更新されるべきではない。
• 広告の視聴を必要としないこと。つまり、広告の視聴の結果として更新されるべきではない。
• ゲームの一般的な使用状況（ゲームを開く、設定を使用するなど）以外であること。
• Google Play ポリシーで定義されているユーザー ID、パスワード、正確な位置情報、健康に関するデータなどの個人情報や機密情報、または攻撃的、冒とく的、性的に露骨な、暴力的、ヘイト コンテンツを含まない。
• すべてのユーザーが利用できる（たとえば、チーム固有のアクションや、特定のレベルのユーザーのみが利用できる、期間限定のライブオプスに限定されるなどであってはいけません）

統合の手順

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

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

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

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

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

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

スキーマを計画する

ゲームの統計データ API を使用して送信できるデータには、プレーヤー イベントと、プレーヤーの進行状況の統計情報に関する事前定義済みイベントの 2 種類があります。

次の例は、さまざまなゲームタイプでプレーヤー イベントがどのように表示されるかを示しています。

プレーヤー イベント

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

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

progressUpdate イベント

ゲームに主要な進行の仕組みがある場合は、このイベントを使用してプレーヤーの現在の進行状況を送信します。イベントには、INT または STRING タイプの「currentProgress」という名前の事前定義されたプロパティが 1 つあります。このプロパティを使用して、メインの進行メカニズムにおけるプレーヤーの進行状況の現在の値を送信することが想定されています。このイベントを使用する場合は、事前定義されたプロパティ「currentProgress」が存在し、このプロパティを使用して進行状況の統計情報を定義する必要があります。

ゲーム内の他の進行状況システム（lifetime highest score や current coin balance など）の現在の値を、このイベントの他のプロパティとして送信できます。

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

統計情報を設定する

繰り返し統計データと進行状況統計データを構成するには、各統計データの計算ロジックと表示情報を定義する必要があります。以下に、さまざまなゲームジャンルの繰り返し統計データの例を示します。繰り返し統計データは通常、ごく少数の（3 ～ 4）ゲーム セッションで、すべてのプレーヤーに対して繰り返し更新され、コア ゲームループに関連付けられている統計データです。

統合の詳細

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

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

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

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

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

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

統合の手順

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

サーバー間統合

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

HTTP リクエスト

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

パスパラメータ

認可と認証

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

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

バックエンド API には、厳格な構造検証の上限があります。

• バッチサイズ: BatchRecordEventsRequest あたり最大 30 個のイベント。
• プロパティ数: PlayerGameEvent あたり最大 25 個のカスタム プロパティ。
• 長さの制限: イベント名（最大 100 文字）、プロパティ キー（最大 100 文字）、プロパティ文字列値（最大 1,024 文字）。
• イベント ID: 有効な 36 文字の UUID 文字列である必要があります。
• 再試行とキャッシュ保存: API が失敗した場合、ローカルで過剰なイベントをキャッシュ保存したり蓄積したりしないでください。30 件を超えるバッチ再試行は拒否されます。バッチサイズの上限を尊重するために、常に再試行をチャンクします。

BatchRecordEventsRequest

詳細については、BatchRecordEventsRequest をご覧ください。

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

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

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,
// 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 // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

レスポンスの本文

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

リクエスト本文の例

イベント: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate イベント

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

クライアントの実装

プラットフォームのゲームの統計データ クライアントの実装については、以下のリソースをご覧ください。

• Android
• Unity
• C++

マイルストーン