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.

Passaggi per l'integrazione

Invia i dati utilizzando l'API Game Stats 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 del 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 dei suoi risultati specifici (ad esempio, tipo di partita, monete raccolte durante la corsa, risultato della partita o numero di colpi alla testa).

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. Consulta le linee guida relative ai file CSV.
• Esegui l'integrazione con l'API Game Stats: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 Eventi flessibili 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 di 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à, ad esempio leghe e sfide social.
    • Fornisci un nome visualizzato univoco per la statistica che vedono i giocatori.
    • Fornisci un testo unico che descriva la statistica. Questa descrizione deve fornire dettagli su come il giocatore la ottiene.
    • Fornisci un'icona univoca che rappresenti la statistica inserendo il nome esatto del file dell'icona nel file CSV.
    • Fornisci un ordine di sequenza per specificare l'ordine in cui un giocatore vedrà le statistiche nel suo profilo giocatore
    • 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 come aggiunto 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.

Linee guida relative ai file CSV per gli eventi

Puoi importare gli eventi utilizzando il file PlayerGameEvent.csv.

Formato PlayerGameEvent.csv

Il file CSV contiene l'evento dichiarato e le relative proprietà come valori separati da virgola nel seguente ordine:

 Event Name,Property Name,Property Type

Se invii l'evento progressUpdate per progressionStat, aggiungi una riga per questo evento. Questo evento deve contenere almeno una proprietà currentProgress di tipo INT o STRINGA, oltre a qualsiasi altra proprietà che vuoi inviare.

Linee guida per i file ZIP per le statistiche

Puoi importare le statistiche contemporaneamente utilizzando un file ZIP. Fai riferimento alla tabella di seguito per i nomi file esatti da utilizzare nel file ZIP:

Formato RepetitiveStatsConfig.csv

Il file CSV contiene l'evento dichiarato e le relative proprietà come valori separati da virgola nel seguente ordine:

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

Se non vuoi utilizzare la condizione di filtro, lascia la cella vuota.

Formato ProgressionStatConfig.csv

Il file CSV contiene l'evento dichiarato e le relative proprietà come valori separati da virgola nel seguente ordine:

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

La statistica di progressione verrà mostrata come prima statistica a un giocatore nel suo profilo giocatore.

Formato StatLocalizations.csv

Il file CSV contiene l'evento dichiarato e le relative proprietà come valori separati da virgola nel seguente ordine:

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

Pianificare lo schema

Puoi inviare due tipi di dati utilizzando l'API Game Stats: eventi giocatore flessibili e un evento predefinito per le statistiche di progressione del giocatore. I seguenti esempi mostrano l'aspetto degli eventi flessibili in vari tipi di giochi.

Eventi giocatore flessibili

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 di loop 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.
• 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 i progressi attuali del giocatore. L'evento ha una proprietà predefinita chiamata "currentProgress" di tipo INT o STRING. Invia il valore dell'avanzamento corrente utilizzando questa proprietà, poiché è l'unico valore che viene visualizzato nell'interfaccia utente delle statistiche di gioco del profilo giocatore.

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.

Dettagli dell'integrazione

Gli endpoint API e l'SDK sono disponibili per i feedback iniziali e saranno disponibili a livello generale (GA) a partire da luglio 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 flessibili rappresentano 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 viene 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

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

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
}

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

Evento progressUpdate

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

Integrazione lato client

L'integrazione lato client sarà resa disponibile utilizzando gli SDK Unity, Java e C++.

L'integrazione lato client per PlayerGameEvent prevede la creazione dell'oggetto evento in Java o Csharp, a seconda dell'SDK, nei punti di attivazione e l'invio utilizzando le funzioni di caricamento fornite dall'SDK.

Analogamente, per l'evento progressUpdate, registra l'avanzamento aggiornato utilizzando la proprietà currentProgress con proprietà aggiuntive definite e inviale utilizzando le funzioni di caricamento fornite dall'SDK.

Eventi

Le integrazioni lato client per PlayerGameEvent sono:

Crea un evento di gioco flessibile per i giocatori

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

Crea progressUpdate evento di gioco del giocatore

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

Registra evento e carica

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

Cronologia