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 soziale Herausforderungen unterstützt.

• Kein Kauf erforderlich (z. B. Kauf von Juwelen). Die Aktualisierung sollte nicht durch einen IAP-Kauf ausgelöst werden.
• Es darf nicht erforderlich sein, sich Werbung anzusehen, um die App zu aktualisieren.
• Es darf sich nicht um eine allgemeine Nutzung des Spiels handeln, z. B. das Öffnen des Spiels oder die Verwendung der Einstellungen.
• Keine personenbezogenen und vertraulichen Nutzerdaten gemäß Play-Richtlinie, einschließlich Nutzer-IDs, Passwörter, genauer 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 oder nur für Nutzer mit einem bestimmten Level verfügbar oder auf zeitlich begrenzte Live-Ops beschränkt)

Integrationsschritte

Senden Sie Daten über die Spielstatistiken 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 von Spielschleifen 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. Übereinstimmungstyp, 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. Weitere Informationen finden Sie unter Ereignisse erstellen.
• 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 Player-Ereignisse und progressUpdate-Ereignisse.
• 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 Property- und 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, in dem die Statistik beschrieben wird. Diese Beschreibung sollte Details dazu enthalten, wie der Spieler sie erhält, und wird Spielern in der Benutzeroberfläche des Spielerprofils 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 sinkender Wert für den Spieler gut ist. Diese Eingabe wird verwendet, um Spielerbewegungen zu feiern.
    • Geben Sie eine optionale Maßeinheit für die Statistik an, z. B. Kilometer, Meilen oder 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 currentProgress-Property 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.

Schema planen

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

Die folgenden Beispiele zeigen, wie Player-Ereignisse in verschiedenen Spieltypen aussehen:

Spieler-Events

Spielerereignisse werden durch bestimmte In‑Game-Momente, den Abschluss von Spielschleifen 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 beim Erkunden gespeicherter Gebiete oder ein abgeschlossenes Level.
  • Da sich wiederholende Statistiken auf wiederholbare Aktionen eines Spielers beziehen sollten, müssen die definierten Ereignisse mit dem Gameplay verknüpft sein.
• Fügen Sie Eigenschaften hinzu, um Kontext zum Ereignis und seinen Ergebnissen bereitzustellen, 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 eine primäre Fortschrittsmechanik hat, verwenden Sie dieses Ereignis, um den aktuellen Fortschritt des Spielers zu senden. Das Ereignis hat eine vordefinierte Property namens „currentProgress“ vom Typ INT oder STRING. Sie müssen den aktuellen Wert des Spielerfortschritts in der primären Fortschrittsmechanik mit dieser Eigenschaft senden. Wenn Sie dieses Ereignis verwenden, muss die vordefinierte Property „currentProgress“ vorhanden sein und mit dieser Property muss eine Fortschrittsstatistik definiert werden.

Sie können den aktuellen Wert für andere Fortschrittssysteme in Ihrem Spiel, z. B. lifetime highest score oder current coin balance, als andere Eigenschaften dieses Ereignisses senden.

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.

Statistiken konfigurieren

Sie müssen Ihre Statistiken zu Wiederholungen und Fortschritt konfigurieren, indem Sie die Berechnungslogik und die Anzeigeinformationen für jede Statistik definieren. Unten finden Sie Beispiele für Statistiken zu Wiederholungen aus verschiedenen Spielgenres. Wiederholte Statistiken sind in der Regel Statistiken, die für jeden Spieler in sehr wenigen (3–4) Spielsitzungen wiederholt aktualisiert werden und mit der zentralen Spielschleife verknüpft sind.

Integrationsdetails

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

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

Wann sollten Sie Daten senden?

Spielerereignisse 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

Für die Back-End-API gelten strenge strukturelle Validierungslimits:

• Batchgröße:Maximal 30 Ereignisse pro BatchRecordEventsRequest.
• Anzahl der Properties:Maximal 25 benutzerdefinierte Properties pro PlayerGameEvent.
• Längenbeschränkungen:Ereignisname (max. 100 Zeichen), Eigenschaftsschlüssel (max. 100 Zeichen) und Eigenschaftsstringwerte (max. 1.024 Zeichen).
• Ereignis-ID:Muss ein gültiger UUID-String mit 36 Zeichen sein.
• Wiederholung und Caching:Vermeiden Sie das lokale Caching oder Ansammeln von zu vielen Ereignissen, wenn die API fehlschlägt, da Batch-Wiederholungen mit mehr als 30 Ereignissen abgelehnt werden. Wiederholungsversuche sollten immer in Blöcke unterteilt werden, um das Batchgrößenlimit 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

Bei Erfolg wird der HTTP-Statuscode „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 Clientimplementierung von Spielstatistiken für Ihre Plattform finden Sie in den folgenden Ressourcen:

• Android
• Unity
• C++

Meilensteine