Spielstatistiken

Spielstatistiken sind kumulative Statistiken zu Ihrem Spiel, die Spieler in ihrem Spielerprofil ansehen können. Mit diesen Statistiken können Spieler ihren Fortschritt im Laufe der Zeit verfolgen, Highlights ansehen und sich mit anderen Spielern vergleichen. Außerdem werden damit Google Play-Funktionen wie Quests und Social Challenges unterstützt.

Integrationsschritte

Senden Sie Daten über die Game Stats API als flexible Spielerereignisse für sich wiederholende Statistiken und ein vordefiniertes Ereignis progressUpdate für die Fortschrittsstatistik. Sie müssen auch die Logik für die Berechnung der Statistiken konfigurieren, die im Spielerprofil angezeigt werden, sowie die zugehörigen Anzeigeinformationen.

Spielerereignisse stellen bestimmte In‑Game-Momente, Abschlüsse des Spielablaufs oder Fortschrittsmeilensteine dar.

Ein Spielerereignis wird so definiert und modelliert:

1. Ein Ereignis wird durch eine bestimmte Aktion des Spielers dargestellt, z. B. das Beenden eines Spiels, das Beenden eines Laufs, das Öffnen einer Truhe oder das Speichern des Fortschritts in einem Bereich.
2. Jede Aktion führt zu bestimmten Ergebnissen oder hat bestimmte Merkmale, die die Aktion definieren. Sie werden als Ereigniseigenschaften modelliert, die Kontext zum Ereignis und seinen spezifischen Ergebnissen liefern, z. B. Spieltyp, während des Laufs gesammelte Münzen, Spielergebnis oder Anzahl der Headshots.

Die Integration umfasst die folgenden Schritte:

• Rohdatenschema deklarieren:Definieren Sie Spielerereignisse mithilfe eines CSV-Uploads in der Play Console. Richtlinien für CSV-Dateien
• Mit der Game Stats API verknüpfen:Senden Sie Rohdaten von Spielern im deklarierten Format für flexible Spielerereignisse und das progressUpdate-Ereignis.
  • Senden Sie alle definierten Ereignisse über die clientseitige oder serverseitige Einbindung. Weitere Informationen finden Sie in den Beispielen für Flexible Events und das progressUpdate-Ereignis.
• ZIP-Datei hochladen:Geben Sie drei CSV-Dateien und alle Bilddateien für Symbole an, die fünf sich wiederholende Statistiken und ein Fortschrittsniveau für Spieler definieren. Weitere Informationen finden Sie unter Richtlinien für ZIP-Dateien. Geben Sie die folgenden Informationen an:
  • CSV-Datei für sich wiederholende Statistiken:
    • Eine eindeutige ID für die Statistik.
    • Geben Sie das Ereignislabel an, das für die Berechnung der Statistik verwendet werden soll. Sie können das Ereignislabel progressUpdate hier nicht verwenden.
      • Geben Sie das Attributlabel an, das für die Berechnung der Statistik verwendet werden soll. Dies muss eine Property des angegebenen Ereignisses sein.
      • Geben Sie den Aggregationstyp (SUM, MAX, MIN oder COUNT) an, um festzulegen, wie die Statistik für das ausgewählte Attributlabel berechnet werden soll.
      • Geben Sie eine optionale Filterbedingung an, um die Logik nur zu berechnen, wenn die Bedingung erfüllt ist. Definieren Sie das Attribut und das Ereignislabel, den Operator (=, < oder >) und den Grenzwert.
    • Fügen Sie ein boolesches Flag ein, um anzugeben, ob die Statistik für Wettbewerbsfunktionen verwendet werden kann.
    • Wenn die Funktion für Wettbewerbsfunktionen verwendet werden kann, gelten für einen echten Spieler Mindest- und Höchstgrenzen pro Stunde. So können wir Spieler identifizieren, die Funktionen wie Ligen und soziale Herausforderungen möglicherweise missbrauchen.
    • Geben Sie einen eindeutigen Anzeigenamen für die Statistik an, die Spieler sehen.
    • Geben Sie einen eindeutigen Text an, der die Statistik beschreibt. Diese Beschreibung sollte Details dazu enthalten, wie der Spieler sie erhält.
    • Geben Sie ein eindeutiges Symbol für die Statistik an, indem Sie den genauen Dateinamen des Symbols in die CSV-Datei eingeben.
    • Geben Sie eine Reihenfolge an, um festzulegen, in welcher Reihenfolge ein Spieler die Statistiken in seinem Spielerprofil sieht.
    • Geben Sie optional an, ob ein steigender oder sinkender Wert für den Spieler von Vorteil ist. Diese Eingabe wird verwendet, um Spielerbewegungen zu feiern.
    • Geben Sie eine optionale Maßeinheit für die Statistik an, z. B. Kilometer, Meilen und Sekunden.
  • CSV-Datei für Statistiken zum Spielerfortschritt:
    • Geben Sie einen eindeutigen Anzeigenamen für den Spielerfortschritt an, der den Spielern angezeigt wird.
    • Stellen Sie ein eindeutiges Symbol für die Statistik bereit.
    • Geben Sie eine Beschreibung für die Fortschrittsstatistik an.
    • Geben Sie optional an, ob ein steigender oder sinkender Wert für den Spieler gut ist. Diese Eingabe wird nur für die Darstellung von Spielerbewegungen verwendet, wenn die Property currentProgress vom Typ INT ist.
    • Geben Sie eine optionale Maßeinheit für die Statistik an, z. B. km, Meilen oder Sekunden.
  • CSV-Datei für die Lokalisierung:Geben Sie lokalisierte Anzeigenamen für alle Statistiken an.
    • Fügen Sie für jede Lokalisierung eine Zeile hinzu.
    • Verwenden Sie den String für den Anzeigenamen der Statistik, wie er in der vorherigen CSV-Datei hinzugefügt wurde, um die Statistik, für die die Lokalisierung hinzugefügt wird, eindeutig zu identifizieren.
    • Geben Sie die Sprache anhand einer Liste von Sprachcodes an.
    • Fügen Sie eine Lokalisierung für den Anzeigenamen in der angegebenen Sprache hinzu.
    • Fügen Sie die Lokalisierung für die Statistikbeschreibung in der angegebenen Sprache hinzu.

Richtlinien für CSV-Dateien für Ereignisse

Sie können Ereignisse über die Datei PlayerGameEvent.csv importieren.

Format „PlayerGameEvent.csv“

Die CSV-Datei enthält das deklarierte Ereignis und seine Attribute als kommagetrennte Werte in der folgenden Reihenfolge:

 Event Name,Property Name,Property Type

Wenn Sie das Ereignis progressUpdate für progressionStat senden, fügen Sie eine Zeile für dieses Ereignis hinzu. Dieses Ereignis muss mindestens eine currentProgress-Property vom Typ INT oder STRING sowie alle anderen Properties enthalten, die Sie senden möchten.

Richtlinien für ZIP-Dateien für Statistiken

Sie können Statistiken gleichzeitig mithilfe einer ZIP-Datei importieren. Die Dateinamen, die Sie für Ihre ZIP-Datei verwenden müssen, finden Sie in der folgenden Tabelle:

Format „RepetitiveStatsConfig.csv“

Die CSV-Datei enthält das deklarierte Ereignis und seine Attribute als kommagetrennte Werte in der folgenden Reihenfolge:

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

Wenn Sie die Filterbedingung nicht verwenden möchten, lassen Sie die Zelle leer.

Format „ProgressionStatConfig.csv“

Die CSV-Datei enthält das deklarierte Ereignis und seine Attribute als kommagetrennte Werte in der folgenden Reihenfolge:

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

Die Fortschrittsstatistik wird Spielern in ihrem Spielerprofil als erste Statistik angezeigt.

Format „StatLocalizations.csv“

Die CSV-Datei enthält das deklarierte Ereignis und seine Attribute als kommagetrennte Werte in der folgenden Reihenfolge:

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

Schema planen

Mit der Game Stats API können Sie zwei Arten von Daten senden: flexible Spielerereignisse und ein vordefiniertes Ereignis für Statistiken zum Spielerfortschritt. Die folgenden Beispiele veranschaulichen, wie flexible Events in verschiedenen Spieltypen aussehen.

Flexible Player-Ereignisse

Spielerereignisse werden durch bestimmte In‑Game-Momente, das Abschließen von Spielzyklen oder Fortschrittsmeilensteine definiert.

• Ereignisse definieren: Ereignisse sind bestimmte In‑Game-Momente, abgeschlossene Spielschleifen oder Fortschrittsmeilensteine:
  • Abschlüsse der Spielschleife, z. B. ein abgeschlossenes Match oder ein abgeschlossener Lauf.
  • Fortschrittsmeilensteine, z. B. der Fortschritt bei der Erkundung gespeicherter Gebiete oder ein abgeschlossenes Level.
• Fügen Sie Eigenschaften hinzu, um Kontext zum Ereignis und seinen Ergebnissen zu liefern, z. B. die Levelnummer, den Spieltyp, den Waffentyp, die Anzahl der Waffen, die Anzahl der Headshots, die Anzahl der gesammelten Münzen, das Spielergebnis, die Rundenzeit oder den Autotyp.
• Senden Sie Ereignisse innerhalb der Gameplay-Sitzung, sobald sie eintreten. Senden Sie beispielsweise ein Ereignis zum Abschluss einer Spielschleife unmittelbar nach dem Abschluss der Schleife.

progressUpdate Ereignis

Wenn Ihr Spiel über einen primären Fortschrittsmechanismus verfügt, verwenden Sie dieses Ereignis, um den aktuellen Fortschritt des Spielers zu senden. Das Ereignis hat eine vordefinierte Eigenschaft namens „currentProgress“ vom Typ INT oder STRING. Senden Sie den Wert des aktuellen Fortschritts mit dieser Property, da dies der einzige Wert ist, der in der Benutzeroberfläche „Spielstatistiken“ des Spielerprofils angezeigt wird.

Da Spieler ihre Profile anhand des aktuellen Fortschritts im Spiel vergleichen können, ist es wichtig, dass der Wert für den aktuellen Fortschritt nach der ersten Integration ohne Verzögerung abgerufen werden kann. Damit der aktuelle Fortschritt für die Spieler korrekt dargestellt wird, sollten Sie das progressUpdate-Ereignis zu Beginn jeder Spielsitzung und immer dann senden, wenn es eine Aktualisierung des aktuellen Fortschritts gibt.

Integrationsdetails

Die API-Endpunkte und das SDK sind für frühes Feedback verfügbar und werden ab Juli 2026 allgemein verfügbar sein. Zeitachse ansehen

In diesem Abschnitt wird gezeigt, wie Sie Ereignisse erstellen und in clientseitigen und serverseitigen Integrationen senden.

Wann sollten Sie Daten senden?

Flexible Events stellen In-Game-Aktionen im Zusammenhang mit dem Abschluss von Spielschleifen oder bestimmten In-Game-Momenten dar. Senden Sie diese Ereignisse, sobald sie eintreten. Senden Sie das Ereignis zum Abschluss der Spielschleife beispielsweise, sobald die Schleife abgeschlossen ist.

progressUpdate Event steht für den aktuellen Fortschritt eines Spielers. Die Daten für die Fortschrittsstatistik sollten in den folgenden Situationen mit diesem Ereignis gesendet werden:

1. Sende den aktuellen Wert sofort, wenn es eine Aktualisierung des aktuellen Fortschritts gibt.
2. Immer dann, wenn ein Spieler das Spiel startet, damit dieser Wert für einen Spieler jederzeit verfügbar ist.

Integration paths

Es gibt zwei Integrationsmöglichkeiten: Client- und Server-zu-Server-Integration.

Server-zu-Server-Integration

Über einen öffentlichen API-Endpunkt können Sie Ereignisse im Anfrage-Payload mit den folgenden Konfigurationen senden:

Pfadparameter

Autorisierung und Authentifizierung

Serverseitige API-Aufrufe folgen den Standardrichtlinien für den serverseitigen Zugriff auf die Play-Spieldienste mit OAuth 2.0. Anfragen müssen ein Inhabertoken enthalten, das mit dem Bereich https://www.googleapis.com/auth/games autorisiert ist.

Flexible Events: Anfragetext

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 Ereignis: Anfragetext

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
}

Antworttext

Bei Erfolg wird der HTTP-Statuscode „200 OK“ mit einem leeren JSON-Objekt zurückgegeben.

Beispiel für einen Anfragetext

Flexibles Ereignis: 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-Ereignis

{
  "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
      }
    }
  ]
}

Clientseitige Integration

Die clientseitige Integration wird über Unity-, Java- und C++-SDKs verfügbar gemacht.

Für die clientseitige Integration von PlayerGameEvent müssen Sie das Ereignisobjekt je nach SDK an den Triggerpunkten in Java oder C# erstellen und es mit den vom SDK bereitgestellten Uploadfunktionen senden.

Für das progressUpdate-Ereignis müssen Sie den aktualisierten Fortschritt mit der currentProgress-Property mit zusätzlichen definierten Properties aufzeichnen und mit den vom SDK bereitgestellten Uploadfunktionen senden.

Ereignisse

Die clientseitige Integration für PlayerGameEvent umfasst Folgendes:

Flexiblen Player-Spielereignis erstellen

// 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-Spielereignis erstellen

// 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);
}

Ereignis aufzeichnen und hochladen

// 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);

Zeitachse