Le statistiche di gioco sono dati cumulativi relativi al tuo gioco che i giocatori possono visualizzare sul proprio profilo giocatore. Queste statistiche consentono ai giocatori di monitorare i progressi complessivi, vedere i momenti migliori e confrontarsi con altri giocatori, oltre a potenziare le funzionalità di Google Play come Missioni, Sfide social e altro ancora in futuro.
Le statistiche di gioco devono:
- Non richiedere un acquisto (ad esempio, l'acquisto di gemme), ovvero non devono essere aggiornati in seguito a un acquisto in-app.
- Non richiedere la visualizzazione di annunci, ovvero non devono aggiornarsi in seguito alla visualizzazione di un annuncio.
- Non essere un utilizzo generico del gioco (ad esempio, apri il gioco, utilizza le impostazioni).
- Non includere dati utente personali e sensibili, come definiti dalle norme di Google Play, inclusi ID utente, password, posizione esatta o dati sulla salute, né contenuti offensivi, volgari, sessualmente espliciti, violenti o che incitano all'odio.
- Essere disponibili 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 LiveOps a tempo limitato e così via)
L'immagine mostra le statistiche di gioco nel profilo giocatore nella scheda Tu. Questa interfaccia utente (UI) nella scheda Tu è disponibile solo a scopo di test. La UI di statistiche di gioco sarà disponibile a settembre 2026.
Tipo di aggregazione
Il tipo di aggregazione indica a Google Play come calcolare una statistica dai valori per evento che invii:
- SUM:utilizza questa opzione per le statistiche cumulative (ad esempio, monete totali raccolte, danni totali inflitti). Il gioco deve inviare l'importo discreto guadagnato durante ogni istanza dell'evento.
- COUNT: da utilizzare per le statistiche che rappresentano il numero di occorrenze di un evento (ad esempio partite giocate, partite vinte). Il gioco deve inviare le istanze di occorrenza degli eventi discreti.
- MAX:utilizza questo tipo solo per gli obiettivi di picco che si verificano una sola volta (ad esempio il punteggio più alto in una singola corsa, la serie di combo massima o il danno più alto in una singola partita). Non utilizzare MAX come soluzione alternativa per visualizzare i totali lifetime dai valori correnti precalcolati.
Requisito di implementazione critico per le statistiche ripetitive
- Invia valori per evento:per ogni evento, invia solo ciò che è accaduto in quell'evento, ad esempio le monete raccolte in una singola corsa. Quindi, imposta un tipo di aggregazione, ad esempio SUM o COUNT, nella configurazione della statistica. In questo modo, le statistiche ripetitive sono riutilizzabili nei meccanismi di coinvolgimento e Google Play può creare le esperienze dei giocatori giuste.
- Non inviare i totali del lifetime value:ad esempio, non monitorare il totale delle monete che un giocatore ha raccolto nel client o nel server di gioco e non inviare questo totale con l'aggregazione MAX. Queste statistiche continueranno a essere mostrate nell'interfaccia utente del profilo giocatore, ma Google Play non potrà utilizzarle per offrire funzionalità gratificanti come campionati, missioni e sprint per migliorare l'esperienza dei giocatori e generare un impatto sul tuo gioco.
Per istruzioni ed esempi sulla corretta modellazione degli eventi, consulta Eventi del giocatore e Configura le statistiche.
Passaggi per l'integrazione
Invia i dati utilizzando l'API Statistiche di gioco come eventi giocatore per le 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 gamer e le relative informazioni di visualizzazione.
Gli eventi giocatore rappresentano momenti di gioco distinti, completamenti di loop di gioco o traguardi di avanzamento.
Un evento del player viene definito e modellato come segue:
- Un evento è rappresentato da un'azione specifica intrapresa dal giocatore, ad esempio il completamento di una partita, il completamento di una corsa, lo sblocco di un forziere o il salvataggio dei progressi in un'area.
- Ogni azione genera determinati risultati o ha determinate caratteristiche che la definiscono. Questi vengono modellati come proprietà degli eventi che forniscono il contesto dell'evento e i relativi risultati specifici (ad esempio, tipo di partita, monete raccolte durante la partita, risultato della partita o numero di colpi alla testa).
L'integrazione prevede i seguenti passaggi:
- Dichiara lo schema dei dati non elaborati:definisci gli eventi dei giocatori utilizzando un caricamento CSV in Play Console. Consulta Crea eventi.
- Integrazione con l'API Statistiche di gioco:invia i dati non elaborati dei giocatori nel formato dichiarato per gli eventi giocatore e l'evento
progressUpdate.- Invia tutti gli eventi definiti utilizzando l'integrazione lato client o lato server.
Per saperne di più, consulta gli esempi di eventi del player e
dell'evento
progressUpdate.
- Invia tutti gli eventi definiti utilizzando l'integrazione lato client o lato server.
Per saperne di più, consulta gli esempi di eventi del player e
dell'evento
- 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 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
progressUpdatequi.- 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 la proprietà e l'etichetta dell'evento, l'operatore (=, <, <=, >= o >) e il valore di soglia.
- Includi un flag booleano per indicare se la statistica può essere utilizzata per le funzionalità competitive.
- Se la funzionalità può essere utilizzata per funzionalità competitive, i limiti orari minimi e massimi per un giocatore autentico. 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 i giocatori vedono.
- 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 file esatto dell'icona nel file CSV.
- Fornisci un input facoltativo che indichi 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 avanzamento 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 che indichi 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 per la descrizione della statistica nella lingua specificata.
- File CSV per statistiche ripetitive:
Pianifica 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 dei giocatori.
I seguenti esempi illustrano l'aspetto degli eventi dei giocatori in vari tipi di giochi:
Eventi giocatore
Gli eventi giocatore sono definiti da momenti di gioco distinti, dal completamento di loop di gioco o da traguardi di progressione.
- Definisci gli eventi come momenti specifici nel gioco, completamenti di loop di gioco o traguardi di progressione:
- Completamenti di cicli di gioco, ad esempio una partita o una corsa completata.
- Traguardi di avanzamento, come i progressi salvati nell'esplorazione di un'area o un livello completato.
- Poiché le statistiche ripetitive devono rappresentare effettivamente azioni ripetibili da un giocatore, gli eventi definiti devono essere associati al gameplay principale.
- Aggiungi proprietà per fornire il contesto dell'evento e dei relativi risultati, ad esempio il numero del 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 della sessione di gameplay non appena si verificano. Ad esempio, invia un evento di completamento del loop di gioco immediatamente dopo il completamento del loop.
Esempi
| Tipo di gioco | Etichetta evento | Momento in-game / Completamento di un evento di progressione / Completamento di un loop di gioco | Risultato | Caratteristiche |
|---|---|---|---|---|
| Rompicapo indie con progressione lineare | chapter_completed | Completamento dell'evento di progressione | N/D | Numero del capitolo, nome del capitolo, numero di tentativi, numero di schermate, numero di mosse, contenuti del capitolo |
| screen_completed | Completamento dell'evento di progressione | Numero del capitolo, nome del capitolo, numero di tentativi, numero di mosse, contenuti del capitolo | ||
| Endless runner 3D | run_completed | Completamento del ciclo di gioco | Monete raccolte, punteggio | Durata della corsa, monete raccolte con il jetpack, booster utilizzato all'inizio della corsa, tavole da surf utilizzate, magneti utilizzati, jumper utilizzato, jetpack utilizzato |
| RPG d'azione open world | areaExplorationProgress | Completamento dell'evento di progressione | Nemici sconfitti, pozioni raccolte | Numero area, Nome area, Percentuale di avanzamento |
| questCompleted | Completamento del ciclo di gioco | N/D | Nome missione | |
| weaponUnlocked | Momento in-game | N/D | Nome dell'arma, livello dell'arma | |
| chestUnlocked | Momento in-game | Minerale di potenziamento raccolto | ||
| Puzzle casual con meta decorativo | puzzleCompleted | Completamento del loop di gioco / Completamento dell'evento di progressione | Monete raccolte, booster raccolti | Numero di mosse, Regalo del maggiordomo utilizzato?, Tipo di livello, numero del livello, booster di colore utilizzati, dinamiti utilizzate |
| cardsCollected | Momento in-game | Carte a 1 stella, carte a 2 stelle, carte a 3 stelle, carte totali | Numero dell'album, nome dell'album | |
| Corse arcade | raceCompleted | Completamento del ciclo di gioco | Rank, NOS used, race_time | Type of race, rating, car_used |
| carUpgraded | Momento in-game | Caratteristica dell'auto che è stata migliorata, livello / valore precedente, livello / valore nuovo | Tipo di auto, livello attuale del garage | |
| Sparatutto battle royale in terza persona | matchCompleted | Completamento del ciclo di gioco | Eliminazioni, colpi alla testa, valore onore | Tipo di partita, tempo di sopravvivenza |
| Simulazione di gestione di eSport | matchCompleted | Completamento del ciclo di gioco | Risultato, numero di goal, goal | Nome della squadra avversaria, nome della squadra che gioca |
| trainingCompleted | Momento in-game | Esercizi completati, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
progressUpdate evento
Se il tuo gioco ha una meccanica di progressione principale, utilizza questo evento per inviare i progressi attuali del giocatore. L'evento ha una proprietà predefinita chiamata "currentProgress" di tipo INT o STRING. Devi inviare il valore corrente dei progressi del giocatore nella meccanica di progressione principale utilizzando questa proprietà. Se utilizzi questo evento, deve essere presente la proprietà predefinita "currentProgress" e deve essere definita una statistica di progressione utilizzando questa proprietà.
Puoi inviare il valore corrente per altri sistemi di progressione nel gioco, come 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 nel gioco, è importante che non ci siano ritardi nel recupero del valore dei progressi attuali dopo la prima integrazione. Per rappresentare con precisione i progressi attuali ai giocatori, devi inviare l'evento progressUpdate all'inizio di ogni sessione di gioco e ogni volta che viene eseguito un aggiornamento dei progressi attuali.
Esempi
| Tipo di gioco | Proprietà currentProgress dell'evento "progressUpdate" |
|---|---|
| Rompicapo a progressione lineare | Numero del capitolo o del livello corrente |
| 3d Endless Runner | Miglior punteggio, saldo attuale dei booster |
| Puzzle casual | Numero del livello attuale, numero di vittorie al primo tentativo, numero di aree completate, numero di collezioni completate |
| Corse arcade | Numero del livello attuale, saldo della valuta |
| RPG d'azione open world | Grado attuale del personaggio, numero del livello attuale |
| Sparatutto in terza persona | Numero del livello attuale |
| Simulazione di esport | Numero di livello manager, numero di livello club |
Configura le statistiche
Dovrai configurare le statistiche ripetitive e di progressione definendo la logica di calcolo e le informazioni di visualizzazione per ogni statistica. Di seguito sono riportati esempi di statistiche ripetitive di diversi generi di giochi. Le statistiche ripetitive sono in genere statistiche che si aggiornano ripetutamente per qualsiasi giocatore in un numero molto ridotto (3-4) di sessioni di gioco e sono associate al ciclo di gioco principale.
Per scoprire quando utilizzare SUM, COUNT o MAX, consulta Scegli il tipo di aggregazione giusto.
| Nome del gioco | Nome visualizzato della statistica di gioco | Proprietà dell'evento | Logica di calcolo [aggregation] | Filtro |
|---|---|---|---|---|
| 3D Endless Runner | Esecuzioni completate | Qualsiasi proprietà dell'evento run_completed | Conteggio | Tutti i valori [nessun filtro] |
| Monete raccolte | Proprietà coins_collected dell'evento run_completed | Somma | N/D | |
| Chiavi raccolte | Proprietà Keys_collected dell'evento run_completed | Somma | N/D | |
| Punteggio di corsa più alto | Proprietà Score dell'evento run_completed | Max | N/D | |
| Esecuzioni con un numero elevato di monete completate | Proprietà coins_collected dell'evento run_completed | Conteggio | Valore > 5000 | |
| Rompicapo a progressione lineare | Capitoli completati | Qualsiasi proprietà dell'evento chapter_completed | Conteggio | Tutti i valori [nessun filtro] |
| Schermate completate | Qualsiasi proprietà dell'evento screen_completed | Conteggio | Tutti i valori [nessun filtro] | |
| Capitoli completati al primo tentativo | Proprietà num_try dell'evento chapter_completed | Conteggio | Num_try = 1 | |
| Schermate completate al primo tentativo | Proprietà Num_try dell'evento screen_completed | Conteggio | Num_try = 1 | |
| RPG d'azione open world | Quest completate | Qualsiasi proprietà dell'evento quest_completed | Conteggio | Tutti i valori [nessun filtro] |
| Aree esplorate | Proprietà perc_progress dell'evento area_exploration_progress | Conteggio | Valore = 100 | |
| Spade sbloccate | Proprietà weapon_type dell'evento weapon_unlocked | Conteggio | Value = "sword" | |
| Nemici sconfitti | Proprietà Enemies_defeated dell'evento area_exploration_progress | Somma | N/D | |
| Pozioni della salute raccolte | Proprietà Enhancement_ores dell'evento chest_unlocked | Somma | N/D | |
| Puzzle casual | Livelli completati | Qualsiasi proprietà dell'evento level_completed | Conteggio | Tutti i valori [nessun filtro] |
| Livelli completati al primo tentativo | Proprietà num_try dell'evento level_completed | Conteggio | Valore = 1 | |
| Color booster utilizzati | Proprietà Color_booster_used dell'evento level_completed | Somma | N/D | |
| Booster bomba utilizzati | Proprietà Bomb_booster_used dell'evento level_completed | Somma | N/D | |
| Carte raccolte | Proprietà total_cards dell'evento cards_collected | Somma | N/D | |
| Corse arcade | Gare vinte | Proprietà Rank dell'evento race_completed | Conteggio | Valore = 1 |
| Gara più veloce | Proprietà race_time dell'evento race_completed | Min | N/D | |
| NOS used | Proprietà NOS_used dell'evento race_completed | Somma | N/D | |
| Gare completate con Mustang | Proprietà car_type dell'evento race_completed | Conteggio | Valore = "Mustang" | |
| Upgrade per l'auto | Qualsiasi proprietà dell'evento car_upgraded | Conteggio | Tutti i valori [nessun filtro] | |
| Sparatutto battle royale in terza persona | Partite vinte | Qualsiasi proprietà dell'evento match_completed | Conteggio | Match_result = TRUE |
| Eliminazioni totali | Proprietà Eliminations dell'evento match_completed | Somma | N/D | |
| Tempo di sopravvivenza più alto | Proprietà survival_time dell'evento match_completed | Max | N/D | |
| Totale colpi alla testa | Proprietà Headshots dell'evento match_completed | Somma | N/D | |
| Valore totale delle competenze | Proprietà skill_value dell'evento match_completed | Somma | N/D | |
| Simulazione di gestione di eSport | Partite vinte | Proprietà Result dell'evento match_completed | Conteggio | Result = "Won" |
| Gol totali segnati | Proprietà goals_scored dell'evento match_completed | Somma | N/D | |
| Partite difficili vinte | Proprietà del risultato dell'evento hard_match_completed | Conteggio | Result = "Won" | |
| Vittoria con la massima differenza reti | Proprietà goal_difference dell'evento match_completed | Max | Result = "Won" | |
| Esercizi di allenamento totali | Proprietà drills_done dell'evento training_completed | Somma | N/D | |
| Attività di formazione completate in totale | Qualsiasi proprietà dell'evento training_completed | Conteggio | N/D |
Dettagli dell'integrazione
Questa sezione mostra come creare eventi e inviarli sia nelle integrazioni lato client sia in quelle lato server.
Quando inviare i dati
Eventi giocatore rappresentano azioni di gioco correlate al completamento di cicli di gioco o a momenti specifici di gioco. Invia questi eventi non appena si verificano. Ad esempio, invia l'evento di completamento del ciclo di gioco non appena il ciclo viene completato.
progressUpdate Event rappresenta il livello di avanzamento attuale di un giocatore.
I dati per la statistica di progressione devono essere inviati utilizzando questo evento nelle seguenti situazioni:
- Ogni volta che è disponibile un aggiornamento dello stato di avanzamento attuale, invia immediatamente l'ultimo valore
- Ogni volta che un giocatore avvia il gioco, per garantire la presenza di questa statistica per un giocatore in ogni 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:
Richiesta HTTP
POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats:
batchRecordEvents
Parametri del percorso
| Parametro | Tipo di dati | Descrizione |
|---|---|---|
| playerId | Stringa | L'ID PGS del giocatore. |
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 utilizzando OAuth 2.0. Le richieste devono includere un token di connessione autorizzato con l'ambito https://www.googleapis.com/auth/games.
Eventi: corpo della richiesta
L'API di backend ha limiti di convalida strutturale rigorosi:
- Dimensioni 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 (massimo 100 caratteri), chiavi delle proprietà (massimo 100 caratteri) e valori delle stringhe delle proprietà (massimo 1024 caratteri).
- ID evento:deve essere una stringa UUID di 36 caratteri valida.
- Nuovo tentativo e memorizzazione nella cache:evita di memorizzare nella cache o di accumulare un numero eccessivo di eventi localmente se l'API non va a buon fine, poiché i nuovi tentativi in batch che superano i 30 eventi verranno rifiutati. Suddividi sempre i nuovi tentativi in blocchi 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 client delle statistiche di gioco per la tua piattaforma, consulta le seguenti risorse:
Traguardi
| Data | Integrazione dell'API Statistiche di gioco | Configurazione delle statistiche di gioco |
| Settembre 2026 | N/D | I giocatori iniziano a visualizzare le statistiche di gioco sul proprio profilo giocatore. |