Statistiche della partita

Le statistiche di gioco sono statistiche cumulative sul tuo gioco che i giocatori possono visualizzare nel loro profilo giocatore. Queste statistiche consentono ai giocatori di monitorare i progressi nel tempo, vedere i momenti salienti e confrontarsi con altri giocatori, oltre a potenziare le funzionalità di Google Play come le missioni, le sfide social e altro ancora in futuro.

• Non richiedere un acquisto (ad esempio, acquista gemme) che non deve essere aggiornato a seguito di un acquisto in-app.
• Non richiedere la visualizzazione di pubblicità, ovvero non devono aggiornarsi a seguito della visualizzazione di una pubblicità.
• Non essere un utilizzo generico del gioco (ad esempio, aprire il gioco; utilizzare le impostazioni).
• Non includere dati utente personali e sensibili, come definiti dalle norme di Google Play, inclusi ID utente, password, posizione esatta o dati sanitari o qualsiasi contenuto offensivo, volgare, sessualmente esplicito, violento o che incita all'odio.
• Essere disponibile per tutti gli utenti (ad esempio, non un'azione specifica per un team o disponibile solo per gli utenti di un determinato livello o limitata a live ops a tempo limitato ecc.)

Passaggi per l'integrazione

Invia i dati utilizzando l'API Statistiche di gioco come eventi giocatore flessibili per statistiche ripetitive e un evento predefinito progressUpdate per la statistica di progressione. Dovrai anche configurare la logica per il calcolo delle statistiche che verranno visualizzate nel profilo giocatore e le informazioni di visualizzazione.

Gli eventi giocatore rappresentano momenti di gioco distinti, completamenti del ciclo di gioco o traguardi di progressione.

Un evento del giocatore è definito e modellato come segue:

1. Un evento è rappresentato da un'azione specifica intrapresa dal giocatore, ad esempio completare una partita, terminare una corsa, sbloccare un forziere o salvare i progressi in un'area.
2. Ogni azione produce determinati risultati o ha determinate caratteristiche che la definiscono. Questi vengono modellati come proprietà evento che forniscono il contesto dell'evento e i suoi risultati specifici (ad esempio, tipo di corrispondenza, monete raccolte durante la corsa, risultato della partita o numero di headshot).

L'integrazione prevede i seguenti passaggi:

• Dichiarare lo schema dei dati non elaborati:definisci gli eventi dei giocatori utilizzando un caricamento CSV in Play Console. Vedi Creare eventi.
• Esegui l'integrazione con l'API Statistiche di gioco:invia i dati non elaborati dei giocatori nel formato dichiarato per eventi flessibili dei giocatori ed eventi progressUpdate.
  • Invia tutti gli eventi definiti utilizzando l'integrazione lato client o lato server. Per saperne di più, consulta gli esempi per gli eventi del player e per l'evento progressUpdate.
• Carica un file ZIP: fornisci 3 file CSV e tutti i file immagine delle icone che definiscono 5 statistiche ripetitive e 1 livello di progressione del giocatore. Per ulteriori informazioni, consulta le linee guida relative ai file ZIP. Includi i seguenti dettagli:
  • File CSV per le statistiche ripetitive:
    • Un ID univoco per la statistica.
    • Specifica l'etichetta evento da utilizzare per il calcolo delle statistiche. Non puoi utilizzare l'etichetta evento progressUpdate qui.
      • Specifica l'etichetta della proprietà da utilizzare per il calcolo delle statistiche. Deve essere una proprietà dell'evento specificato.
      • Specifica il tipo di aggregazione (SUM, MAX, MIN o COUNT) per determinare come calcolare la statistica sull'etichetta della proprietà selezionata.
      • Specifica una condizione di filtro facoltativa per calcolare la logica solo quando la condizione è soddisfatta. Definisci l'etichetta della proprietà e dell'evento, l'operatore (=, <, <=, >= o >) e il valore soglia.
    • Includi un flag booleano per indicare se la statistica può essere utilizzata per funzionalità competitive.
    • Se la funzionalità può essere utilizzata per funzionalità competitive, i limiti orari minimi e massimi per un giocatore reale. Questi dati verranno utilizzati per identificare i giocatori che potrebbero fare un uso improprio delle funzionalità come i campionati e le sfide social.
    • Fornisci un nome visualizzato univoco per la statistica che vedono i giocatori.
    • Fornisci un testo univoco che descriva la statistica. Questa descrizione deve fornire dettagli su come il giocatore la ottiene e verrà mostrata ai giocatori nell'interfaccia utente del profilo giocatore.
    • Fornisci un'icona univoca che rappresenti la statistica inserendo il nome esatto del file dell'icona nel file CSV.
    • Fornisci un input facoltativo per indicare se un valore crescente o decrescente è positivo per il giocatore. Questo input verrà utilizzato per celebrare i movimenti dei giocatori.
    • Fornisci un'unità di misura facoltativa per la statistica, ad esempio km, miglia e secondi.
  • File CSV per la statistica di progressione del giocatore:
    • Fornisci un nome visualizzato univoco per la progressione del giocatore che i giocatori vedono.
    • Fornisci un'icona univoca che rappresenti la statistica.
    • Fornisci una descrizione per la statistica di avanzamento.
    • Fornisci un input facoltativo per indicare se un valore crescente o decrescente è positivo per il giocatore. Questo input verrà utilizzato per celebrare i movimenti dei giocatori solo quando la proprietà currentProgress è di tipo INT.
    • Fornisci un'unità di misura facoltativa per la statistica, ad esempio km, miglia, secondi.
  • File CSV per la localizzazione: fornisci nomi visualizzati localizzati per tutte le statistiche.
    • Aggiungi una riga per ogni localizzazione.
    • Utilizza la stringa del nome visualizzato della statistica aggiunta nel file CSV precedente per identificare in modo univoco la statistica a cui viene aggiunta la localizzazione.
    • Specifica la lingua da un elenco di codici lingua.
    • Aggiungi la localizzazione per il nome visualizzato nella lingua specificata.
    • Aggiungi la localizzazione della descrizione della statistica nella lingua specificata.

Pianificare lo schema

Puoi inviare due tipi di dati utilizzando l'API Statistiche di gioco: eventi giocatore e un evento predefinito per le statistiche di progressione del giocatore.

I seguenti esempi illustrano l'aspetto degli eventi del giocatore in vari tipi di giochi:

Eventi giocatore

Gli eventi giocatore sono definiti da momenti distinti in-game, completamenti del ciclo di gioco o traguardi di progressione.

• Definisci gli eventi come momenti specifici in-game, completamenti del ciclo di gioco o traguardi di progressione:
  • Completamenti del ciclo di gioco, ad esempio una partita o una corsa completata.
  • Traguardi di progressione, ad esempio l'avanzamento dell'esplorazione di un'area salvata o un livello completato.
  • Poiché le statistiche ripetitive devono rappresentare veramente le azioni ripetibili di un giocatore, gli eventi definiti devono essere associati al gameplay principale.
• Aggiungi proprietà per fornire il contesto dell'evento e dei suoi risultati, ad esempio il numero di livello, il tipo di partita, il tipo di arma, il numero di armi, i colpi alla testa, le monete raccolte, il risultato della partita, il tempo sul giro o il tipo di auto.
• Invia gli eventi all'interno della sessione di gioco non appena si verificano. Ad esempio, invia un evento di completamento del ciclo di gioco immediatamente dopo il completamento del ciclo.

progressUpdate Evento

Se il tuo gioco ha una meccanica di progressione principale, utilizza questo evento per inviare lo stato di avanzamento attuale del giocatore. L'evento ha una proprietà predefinita denominata "currentProgress" di tipo INT o STRING. Devi inviare il valore attuale dei progressi del giocatore nella meccanica di progressione principale utilizzando questa proprietà. Se utilizzi questo evento, la proprietà predefinita "currentProgress" deve essere presente e deve essere definita una statistica di avanzamento utilizzando questa proprietà.

Puoi inviare il valore attuale per altri sistemi di progressione nel tuo gioco, ad esempio lifetime highest score o current coin balance, come altre proprietà di questo evento.

Poiché i giocatori possono confrontare i loro profili in base ai progressi attuali all'interno del gioco, è importante che non vi siano ritardi nell'ottenimento del valore dei progressi attuali dopo la prima integrazione. Per rappresentare l'avanzamento attuale accurato per i giocatori, devi inviare l'evento progressUpdate all'inizio di ogni sessione di gioco e ogni volta che viene aggiornato l'avanzamento attuale.

Configurare le statistiche

Dovrai configurare le statistiche ripetitive e di progressione definendo la logica di calcolo e visualizzando le informazioni su ciascuna statistica. Di seguito sono riportati esempi di statistiche ripetitive di diversi generi di giochi. Le statistiche ripetitive sono in genere statistiche che vengono aggiornate ripetutamente per qualsiasi giocatore in un numero molto ridotto (3-4) di sessioni di gioco e sono associate al ciclo di gioco principale.

Dettagli dell'integrazione

Gli endpoint API e l'SDK sono disponibili per ricevere feedback in anteprima e saranno disponibili al pubblico generale (GA) a partire da agosto 2026. Visualizza la cronologia

Questa sezione mostra come creare eventi e inviarli nelle integrazioni lato client e lato server.

Quando inviare i dati

Gli eventi dei giocatori rappresentano le azioni in-game correlate al completamento del ciclo di gioco o a momenti specifici in-game. Invia questi eventi non appena si verificano. Ad esempio, invia l'evento di completamento del ciclo di gioco non appena il ciclo è completato.

progressUpdate Evento rappresenta il livello di avanzamento attuale di un giocatore. I dati per la statistica di avanzamento devono essere inviati utilizzando questo evento nelle seguenti situazioni:

1. Ogni volta che viene aggiornato lo stato di avanzamento corrente, invia immediatamente l'ultimo valore
2. Ogni volta che un giocatore avvia il gioco, per garantire la presenza di questa statistica per un giocatore in qualsiasi momento.

Integration paths

Esistono due percorsi di integrazione: client e server-to-server.

Integrazione server-server

Un endpoint API pubblico ti consente di inviare eventi nel payload della richiesta utilizzando le seguenti configurazioni:

Parametri del percorso

Autorizzazione e autenticazione

Le chiamate API server-to-server seguono le linee guida standard per l'accesso lato server ai servizi per i giochi di Play tramite OAuth 2.0. Le richieste devono includere un token di connessione autorizzato con l'ambito https://www.googleapis.com/auth/games.

Eventi flessibili: corpo della richiesta

L'API di backend ha limiti rigorosi di convalida strutturale:

• Dimensione del batch:un massimo di 30 eventi per BatchRecordEventsRequest.
• Numero di proprietà:un massimo di 25 proprietà personalizzate per PlayerGameEvent.
• Limiti di lunghezza:nome evento (max 100 caratteri), chiavi proprietà (max 100 caratteri) e valori stringa proprietà (max 1024 caratteri).
• ID evento:deve essere una stringa UUID di 36 caratteri valida.
• Ritentativi e memorizzazione nella cache:evita di memorizzare nella cache o accumulare eventi eccessivi localmente se l'API non funziona, poiché i tentativi di batch che superano i 30 eventi verranno rifiutati. Riprova sempre a eseguire il chunk per rispettare il limite di dimensioni del batch.

BatchRecordEventsRequest

Consulta 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"
}

Evento progressUpdate: corpo della richiesta

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")
}

Corpo della risposta

In caso di esito positivo, restituisce uno stato HTTP 200 OK con un oggetto JSON vuoto.

Esempio di corpo della richiesta

Evento: 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
        }
      }
    }
  ]
}

Evento 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
      }
    }
  ]
}

Implementazioni client

Per scoprire di più sull'implementazione del client delle statistiche di gioco per la tua piattaforma, consulta le seguenti risorse:

• Android
• Unity
• C++

Traguardi