Spielstatistiken

Spielstatistiken sind kumulative Statistiken zu deinem Spiel, die Spieler in ihrem Spielerprofil einsehen können. Mit diesen Statistiken können Spieler ihre gesamten Fortschritte verfolgen, Highlights ansehen und sich mit anderen Spielern vergleichen. Zudem bilden sie die Basis für Google Play-Funktionen wie Missionen, soziale Herausforderungen und zukünftige Erweiterungen.

Spielstatistiken müssen:

• Sie dürfen keinen Kauf erfordern (z. B. Kauf von Edelsteinen), d. h. sie dürfen nicht als Folge eines In-App-Kaufs aktualisiert werden.
• Sie dürfen nicht das Ansehen von Werbung erfordern, d. h., sie dürfen nicht als Folge des Ansehens von Werbung aktualisiert werden.
• Keine allgemeine Nutzung des Spiels (z. B. „Öffne das Spiel“ oder „Verwende die Einstellungen“)
• Keine personenbezogenen und vertraulichen Nutzerdaten gemäß der Definition in den Google Play-Richtlinien enthalten, einschließlich Nutzer-IDs, Passwörtern, genauen Standort- oder Gesundheitsdaten, oder anstößige, vulgäre, sexuell explizite, gewalttätige oder hasserfüllte Inhalte.
• Für alle Nutzer verfügbar sein (z. B. keine teamspezifische Aktion, nicht nur für Nutzer einer bestimmten Stufe verfügbar oder nicht auf zeitlich begrenzte LiveOps beschränkt)

Die Abbildung zeigt die Spielstatistiken im Spielerprofil auf dem Tab Mein Play. Diese Benutzeroberfläche auf dem Tab Mein YouTube ist nur zu Testzwecken verfügbar. Die Benutzeroberfläche für Spielstatistiken wird im September 2026 verfügbar sein.

Aggregationstyp

Der Aggregationstyp gibt Google Play an, wie ein Statistikwert aus den von dir gesendeten Werten pro Ereignis berechnet werden soll:

• SUM:Verwende diese Option für kumulative Statistiken (z. B. Gesamtzahl der gesammelten Münzen, Gesamtschaden). Das Spiel muss den genauen Betrag senden, der während jeder Ereignisinstanz verdient wurde.
• COUNT:Wird für Statistiken verwendet, die die Anzahl der Vorkommen eines Ereignisses darstellen (z. B. gespielte Spiele, gewonnene Spiele). Das Spiel muss die einzelnen Instanzen des Ereignisses senden.
• MAX:Nur für einmalige Spitzenleistungen verwenden (z. B. höchste Punktzahl in einem einzelnen Durchlauf, maximale Kombinationsserie oder höchster Schaden in einem einzelnen Match). Verwenden Sie MAX nicht als Behelfslösung, um die Gesamtsummen für die Lebensdauer aus vorberechneten laufenden Werten anzuzeigen.

Wichtige Implementierungsanforderung für wiederholte Statistiken

• Ereignisspezifische Werte senden:Senden Sie für jedes Ereignis nur die Daten, die sich auf dieses Ereignis beziehen, z. B. die in einem einzelnen Durchlauf gesammelten Münzen. Legen Sie dann in der Statistikkonfiguration einen Aggregationstyp wie SUM oder COUNT fest. So wird sichergestellt, dass wiederkehrende Statistiken für verschiedene Interaktions- und Bindungsmechanismen wiederverwendet werden können und Google Play die richtigen Spielerlebnisse erstellen kann.
• Keine Gesamtsummen senden:Erfassen Sie beispielsweise nicht die Gesamtzahl der Münzen, die ein Spieler jemals in Ihrem Spielclient oder auf Ihrem Server gesammelt hat, und senden Sie diese Gesamtsumme nicht mit der MAX-Aggregation. Diese Statistiken werden weiterhin in der Benutzeroberfläche des Spielerprofils angezeigt, aber Google Play kann sie nicht für Funktionen wie Ligen, Quests und Sprints verwenden, um das Spielerlebnis zu verbessern und die Wirkung Ihres Spiels zu steigern.

Anleitungen und Beispiele zur korrekten Ereignismodellierung finden Sie unter Spielerereignisse und Statistiken konfigurieren.

Integrationsschritte

Sende Daten über die Game Stats API als Spielerereignisse für wiederkehrende Statistiken und ein vordefiniertes Ereignis progressUpdate für die Fortschrittsstatistik. Du musst auch die Logik für die Berechnung der Statistiken, die im Spielerprofil angezeigt werden, und die zugehörigen Anzeigeinformationen konfigurieren.

Spielerereignisse stellen bestimmte Momente im Spiel, abgeschlossene Spielschleifen oder Meilensteine im Spielfortschritt dar.

Ein Spielerereignis wird so definiert und modelliert:

1. Ein Ereignis wird durch eine bestimmte Aktion des Spielers dargestellt, z. B. das Abschließen eines Matches, das Beenden eines Laufs, das Freischalten 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. Diese werden als Ereignisattribute modelliert, die Kontext zum Ereignis und seinen spezifischen Ergebnissen liefern (z. B. Match-Typ, während des Laufs gesammelte Münzen, Match-Ergebnis oder Anzahl der Kopfschüsse).

Die Integration umfasst die folgenden Schritte:

• Rohdatenschema deklarieren:Definiere Spielerereignisse mithilfe eines CSV-Uploads in der Play Console. Weitere Informationen finden Sie unter Ereignisse erstellen.
• In die Game Stats API einbinden:Sende Rohdaten von Spielern im deklarierten Format für Spielerereignisse und das Ereignis progressUpdate.
  • Senden Sie alle definierten Ereignisse über die client- oder serverseitige Integration. Weitere Informationen findest du in den Beispielen für Player-Ereignisse und das progressUpdate-Ereignis.
• ZIP-Datei hochladen:Stellen Sie drei CSV-Dateien und alle Symboldateien bereit, die fünf wiederholbare Statistiken und eine Spielerfortschrittsstufe definieren. Weitere Informationen finden Sie in den Richtlinien für ZIP-Dateien. Geben Sie die folgenden Informationen an:
  • CSV-Datei für wiederkehrende Statistiken:
    • Eine eindeutige ID für die Statistik.
    • Geben Sie das Ereignislabel an, das für die Statistikberechnung verwendet werden soll. Sie können das Ereignislabel progressUpdate hier nicht verwenden.
      • Geben Sie das Attributlabel an, das für die Statistikberechnung 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, damit die Logik nur berechnet wird, wenn die Bedingung erfüllt ist. Definieren Sie das Attribut- und Ereignislabel, den Operator (=, <, <=, >= oder >) und den Schwellenwert.
    • Fügen Sie ein boolesches Flag hinzu, um anzugeben, ob die Statistik für Wettbewerbsfunktionen verwendet werden kann.
    • Wenn die Funktion für Wettbewerbsfunktionen verwendet werden kann, dann Mindest- und Höchststundenlimits für einen echten Spieler. So können wir Spieler identifizieren, die Funktionen wie Ligen und soziale Herausforderungen missbrauchen.
    • Geben Sie einen eindeutigen Anzeigenamen für die Statistik an, die Spieler sehen.
    • Geben Sie einen eindeutigen Text ein, der die Statistik beschreibt. Diese Beschreibung sollte Details dazu enthalten, wie der Spieler sie erhält, und wird Spielern in der Spielerprofil-UI angezeigt.
    • Geben Sie ein eindeutiges Symbol für die Statistik an, indem Sie den genauen Dateinamen des Symbols in die CSV-Datei eingeben.
    • Geben Sie optional an, ob ein steigender oder ein sinkender Wert für den Spieler gut ist. Diese Eingabe wird verwendet, um die Bewegungen der Spieler zu feiern.
    • Geben Sie eine optionale Maßeinheit für die Statistik an, z. B. km, Meilen und Sekunden.
  • CSV-Datei für die Statistik zum Spielerfortschritt:
    • Geben Sie einen eindeutigen Anzeigenamen für den Spielerfortschritt an, den Spieler sehen.
    • Stelle ein eindeutiges Symbol für die Statistik bereit.
    • Geben Sie eine Beschreibung für die Fortschrittsstatistik ein.
    • Geben Sie optional an, ob ein steigender oder ein sinkender Wert für den Spieler gut ist. Diese Eingabe wird nur dann zum Feiern von Spielerbewegungen verwendet, wenn das Attribut 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, der 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 aus einer Liste von Sprachcodes an.
    • Fügen Sie eine Lokalisierung für den Anzeigenamen in der angegebenen Sprache hinzu.
    • Fügen Sie eine Lokalisierung für die Statistikbeschreibung in der angegebenen Sprache hinzu.

Schema planen

Mit der Spielstatistiken API können Sie zwei Arten von Daten senden: Spieleraktionen und ein vordefiniertes Ereignis für Statistiken zum Spielfortschritt.

Die folgenden Beispiele zeigen, wie Spielerereignisse bei verschiedenen Spieltypen aussehen:

Spieleraktionen

Spielerereignisse werden durch bestimmte Momente im Spiel, abgeschlossene Spielschleifen oder Fortschrittsmeilensteine definiert.

• Definiere Ereignisse als bestimmte Momente im Spiel, abgeschlossene Spielschleifen oder Meilensteine im Spielfortschritt:
  • Abschluss von Spielschleifen, z. B. ein abgeschlossenes Spiel oder ein abgeschlossener Lauf.
  • Fortschrittsmeilensteine, z. B. gespeicherter Fortschritt bei der Erkundung eines Bereichs oder ein abgeschlossenes Level.
  • Da wiederholte Statistiken wirklich wiederholbare Aktionen eines Spielers darstellen sollten, sollten die definierten Ereignisse mit dem Kern-Gameplay verknüpft sein.
• Fügen Sie Properties hinzu, um Kontext zum Ereignis und seinen Ergebnissen bereitzustellen, z. B. Levelnummer, Matchtyp, Waffentyp, Anzahl der Waffen, Kopfschüsse, gesammelte Münzen, Matchergebnis, Rundenzeit oder Autotyp.
• Senden Sie Ereignisse innerhalb der Spielsitzung, sobald sie auftreten. Senden Sie beispielsweise ein Ereignis zum Abschluss der Spielschleife, sobald die Schleife abgeschlossen ist.

progressUpdate Ereignis

Wenn Ihr Spiel eine primäre Fortschrittsmechanik hat, verwenden Sie dieses Ereignis, um den aktuellen Fortschritt des Spielers zu senden. Das Ereignis hat ein vordefiniertes Attribut namens „currentProgress“ vom Typ INT oder STRING. Du solltest den aktuellen Wert des Spielerfortschritts in der primären Fortschrittsmechanik mit dieser Property senden. Wenn du dieses Ereignis verwendest, muss die vordefinierte Property „currentProgress“ vorhanden sein und es muss eine Fortschrittsstatistik mit dieser Property definiert werden.

Du kannst den aktuellen Wert für andere Fortschrittssysteme in deinem Spiel, z. B. lifetime highest score oder current coin balance, als andere Properties dieses Ereignisses senden.

Da Spieler ihre Profile anhand des aktuellen Fortschritts im Spiel vergleichen können, ist es wichtig, dass der aktuelle Fortschrittswert nach der ersten Integration ohne Verzögerung abgerufen wird. Damit Spieler den aktuellen Fortschritt sehen, sollten Sie das Ereignis progressUpdate zu Beginn jeder Spielsitzung und immer dann senden, wenn sich der aktuelle Fortschritt ändert.

Statistiken konfigurieren

Du musst deine wiederkehrenden und Fortschrittsstatistiken konfigurieren, indem du die Berechnungslogik und die Anzeigeinformationen für jede Statistik definierst. Unten findest du Beispiele für wiederkehrende Statistiken aus verschiedenen Spielgenres. Wiederkehrende Statistiken sind in der Regel Statistiken, die für alle Spieler in wenigen (3–4) Spielsitzungen wiederholt aktualisiert werden und mit der Kernspielschleife verknüpft sind.

Informationen dazu, wann Sie SUM, COUNT oder MAX verwenden sollten, finden Sie unter Den richtigen Aggregationstyp auswählen.

Integrationsdetails

In diesem Abschnitt wird beschrieben, wie Sie Ereignisse erstellen und sowohl in clientseitigen als auch in serverseitigen Integrationen senden.

Wann sollten Sie Daten senden?

Spielerereignisse stellen In-Game-Aktionen dar, die sich auf den Abschluss von Spielschleifen oder bestimmte In-Game-Momente beziehen. Senden Sie diese Ereignisse, sobald sie auftreten. Senden Sie beispielsweise das Ereignis für den Abschluss der Spielschleife, sobald die Schleife abgeschlossen ist.

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

1. Wenn es ein Update zum aktuellen Fortschritt gibt, senden Sie sofort den neuesten Wert.
2. Diese Statistik wird jedes Mal aktualisiert, wenn ein Spieler das Spiel startet, damit sie immer verfügbar ist.

Integration paths

Es gibt zwei Integrationspfade: Client und Server-zu-Server.

Server-zu-Server-Integration

Über einen öffentlichen API-Endpunkt können Sie Ereignisse in der Anfragenutzlast mit den folgenden Konfigurationen senden:

HTTP-Anfrage

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

Pfadparameter

Autorisierung und Authentifizierung

Server-zu-Server-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.

Ereignisse: Anfragetext

Die Backend-API hat strenge Einschränkungen für die strukturelle Validierung:

• Batchgröße: Maximal 30 Ereignisse pro BatchRecordEventsRequest.
• Anzahl der Properties: Maximal 25 benutzerdefinierte Eigenschaften pro PlayerGameEvent.
• Längenbeschränkungen:Ereignisname (max. 100 Zeichen), Attributschlüssel (max. 100 Zeichen) und Attributstringwerte (max. 1.024 Zeichen).
• Ereignis-ID:Muss ein gültiger UUID-String mit 36 Zeichen sein.
• Wiederholung und Caching: Vermeiden Sie das Caching oder die lokale Akkumulation übermäßiger Ereignisse, wenn die API fehlschlägt, da Batch-Wiederholungen mit mehr als 30 Ereignissen abgelehnt werden. Teilen Sie Wiederholungsversuche immer in Blöcke auf, um das Limit für die Batchgröße einzuhalten.

BatchRecordEventsRequest

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

Antworttext

Wenn der Vorgang erfolgreich ist, wird der HTTP-Status „200 OK“ mit einem leeren JSON-Objekt zurückgegeben.

Beispiel für einen Anfragetext

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

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

Clientimplementierungen

Informationen zur Implementierung des Spielstatistik-Clients für Ihre Plattform finden Sie in den folgenden Ressourcen:

• Android
• Unity
• C++

Meilensteine