Las estadísticas del juego son estadísticas acumulativas sobre tu juego que los jugadores pueden ver en su perfil de gamer. Estas estadísticas permiten que los jugadores hagan un seguimiento de su progreso a lo largo del tiempo, vean los momentos destacados y se comparen con otros jugadores, y potencian funciones de Google Play, como las misiones, los desafíos sociales y mucho más en el futuro.
Pasos para la integración
Envía datos con la API de Game Stats como eventos flexibles del jugador para las estadísticas repetitivas y un evento predefinido progressUpdate para la estadística de progresión. También deberás configurar la lógica para calcular las estadísticas que aparecerán en el perfil de jugador y su información de visualización.
Los eventos de jugadores representan momentos distintos en el juego, finalizaciones del bucle de juego o hitos de progresión.
Un evento de jugador se define y modela de la siguiente manera:
- Un evento se representa con una acción específica que realiza el jugador, como completar una partida, terminar una carrera, desbloquear un cofre o guardar el progreso en un área.
- Cada acción genera ciertos resultados o tiene ciertas características que la definen. Se modelan como propiedades de eventos que proporcionan contexto sobre el evento y sus resultados específicos (por ejemplo, tipo de partida, monedas recolectadas durante esa ejecución, resultado de la partida o recuento de disparos a la cabeza).
La integración consta de los siguientes pasos:
- Declara el esquema de datos sin procesar: Define los eventos de los jugadores con una carga de CSV en Play Console. Consulta los lineamientos para archivos CSV.
- Integración con la API de Game Stats: Envía datos sin procesar de los jugadores en el formato declarado para eventos de jugadores flexibles y el evento
progressUpdate.- Envía todos los eventos definidos con la integración del cliente o del servidor.
Para obtener más información, consulta los ejemplos de Eventos flexibles y el evento
progressUpdate.
- Envía todos los eventos definidos con la integración del cliente o del servidor.
Para obtener más información, consulta los ejemplos de Eventos flexibles y el evento
- Sube un archivo ZIP: Proporciona 3 archivos CSV y todos los archivos de imagen de íconos que definan 5 estadísticas repetitivas y 1 nivel de progresión del jugador.
Para obtener más información, consulta los Lineamientos para archivos ZIP.
Incluye los siguientes detalles:
- Archivo CSV para estadísticas repetitivas:
- Es un ID único para la estadística.
- Especifica la etiqueta del evento que se usará para el cálculo de estadísticas. Aquí no puedes usar la etiqueta del evento
progressUpdate.- Especifica la etiqueta de propiedad que se usará para el cálculo de estadísticas. Debe ser una propiedad del evento especificado.
- Especifica el tipo de agregación (SUM, MAX, MIN o COUNT) para determinar cómo calcular la estadística en la etiqueta de propiedad seleccionada.
- Especifica una condición de filtro opcional para calcular la lógica solo cuando se cumpla la condición. Define la propiedad y la etiqueta del evento, el operador (=, < o >) y el valor del umbral.
- Incluye una marca booleana para indicar si la estadística se puede usar para las funciones competitivas.
- Si la función se puede usar para funciones competitivas, se indican los límites mínimos y máximos por hora para un jugador genuino. Esto nos permitirá identificar a los jugadores que podrían estar haciendo un uso inadecuado de las funciones, como las ligas y los desafíos sociales.
- Proporciona un nombre visible único para la estadística que verán los jugadores.
- Proporciona un texto único que describa la estadística. Esta descripción debe proporcionar detalles sobre cómo el jugador la obtiene.
- Proporciona un ícono único que represente la estadística ingresando el nombre de archivo exacto del ícono en el archivo CSV.
- Proporciona un orden de secuencia para especificar el orden en el que un jugador vería las estadísticas en su perfil de jugador.
- Proporciona una entrada opcional que indica si un valor creciente o decreciente es bueno para el jugador. Esta entrada se usará para celebrar los movimientos de los jugadores.
- Proporciona una unidad de medida opcional para la estadística, como km, millas y segundos.
- Archivo CSV para la estadística de progresión del jugador:
- Proporciona un nombre visible único para la progresión del jugador que verán los jugadores.
- Proporciona un ícono único que represente la estadística.
- Proporciona una descripción para la estadística de progresión.
- Proporciona una entrada opcional que indica si un valor creciente o decreciente es bueno para el jugador. Esta entrada se usará para celebrar los movimientos del jugador solo cuando la propiedad
currentProgresssea de tipo INT. - Proporciona una unidad de medida opcional para la estadística, como km, millas o segundos.
- Archivo CSV para la localización: Proporciona nombres visibles localizados para todas las estadísticas.
- Agrega una fila para cada localización.
- Usa la cadena del nombre visible de la estadística tal como se agregó en el CSV anterior para identificar de forma única la estadística para la que se agrega la localización.
- Especifica el idioma en una lista de códigos de idioma.
- Agrega la localización del nombre visible en el idioma especificado.
- Agrega la localización de la descripción de la estadística en el idioma especificado.
- Archivo CSV para estadísticas repetitivas:
Lineamientos para los archivos CSV de eventos
Puedes importar eventos con el archivo PlayerGameEvent.csv.
| Nombre de archivo | Obligatorio u opcional |
| PlayerGameEvent.csv | Obligatorio |
Formato de PlayerGameEvent.csv
El CSV contiene el evento declarado y sus propiedades como valores separados por comas en el siguiente orden:
Event Name,Property Name,Property Type
Si envías el evento progressUpdate para el progressionStat, agrega una fila para este evento. Este evento debe contener, al menos, una propiedad currentProgress de tipo INT o STRING, además de cualquier otra propiedad que desees enviar.
Tabla de ejemplos
| Nombre del evento | Nombre de la propiedad | Tipo de propiedad |
|---|---|---|
| matchCompleted | duración | DOUBLE |
| matchCompleted | mata | INT |
| matchCompleted | isWinner | BOOLEAN |
| matchCompleted | matchType | CADENA (UTF-8) |
| itemCollected | coinsAmount | INT |
| itemCollected | weaponType | CADENA (UTF-8) |
| progressUpdate | currentProgress | INT |
Lineamientos para archivos ZIP de estadísticas
Puedes importar estadísticas a la vez con un archivo ZIP. Consulta la tabla para conocer los nombres de archivo precisos que debes usar en tu archivo ZIP:
| Nombre del archivo | Obligatorio u opcional | Accepted values |
|---|---|---|
RepetitiveStatsConfig.csv
|
Obligatorio | Son metadatos para muchos eventos. |
ProgressionStatConfig.csv
|
Obligatorio | Es el evento declarado y sus propiedades. |
StatLocalizations.csv
|
Opcional | Proporciona traducciones de los nombres y las descripciones de los logros. |
| Archivos de íconos | Obligatorio | Íconos en formato PNG, JPEG o JPG de 512 x 512 |
Formato de RepetitiveStatsConfig.csv
El CSV contiene el evento declarado y sus propiedades como valores separados por comas en el siguiente orden:
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
En caso de que no quieras usar la condición de filtro, deja la celda en blanco.
Tabla de ejemplos
| ID de la estadística | Nombre del evento | Nombre de la propiedad | Agregación | Nombre visible de la estadística | Descripción de la estadística | Propiedad de filtro (opcional) | Operador de filtro (opcional) | Valor del filtro (opcional) | Es competitivo | minLimit | maxLimit | Nombre del archivo del ícono | Número de secuencia | Buena dirección de valor | unidad |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | matchCompleted | duración | MAX | Supervivencia de la coincidencia más larga | Esto denota el tiempo de supervivencia de un jugador en cualquier partida. | isWinner | = | TRUE | TRUE | 0 | 50 | stat1.png | 1 | En disminución | segundos |
| 2 | matchCompleted | isWinner | COUNT | Partidos ganados | Indica la cantidad de partidos que ganó un jugador. | isWinner | = | TRUE | TRUE | 0 | 50 | stat3.png | 2 | En aumento | |
| 3 | matchCompleted | mata | SUM | Asesinatos en partidas 1 contra 1 | Cantidad de eliminaciones realizadas en los enfrentamientos 1 contra 1 | matchType | = | "1-on-1" | FALSO | stat4.png | 4 | En aumento | |||
| 4 | itemCollected | coinsAmount | SUM | Oro total recolectado | El jugador recolecta monedas mientras juega un partido | weaponType | = | "sword" | FALSO | stat2.png | 3 | En aumento |
Formato de ProgressionStatConfig.csv
El CSV contiene el evento declarado y sus propiedades como valores separados por comas en el siguiente orden:
Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit
La estadística de progresión se mostrará como la primera estadística para un jugador en su perfil de gamer.
Tabla de ejemplos
| ID de la estadística | Nombre visible de la estadística | Descripción de la estadística | Nombre del archivo de ícono | Buena dirección de valor |
| 5 | Nivel | Los jugadores acumulan XP jugando partidos y suben de nivel. | Level.png | aumento |
Formato de StatLocalizations.csv
El CSV contiene el evento declarado y sus propiedades como valores separados por comas en el siguiente orden:
Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description
Tabla de ejemplos
| ID de la estadística | Nombre visible de la estadística | Código de idioma | Nombre de la estadística localizada (UTF-8) | Localized Stat Description (UTF-8) | 1 | Supervivencia de la coincidencia más larga | es | Supervivencia más larga en partidos | Esto denota el tiempo de supervivencia de una jugadora en cualquier partido. | 1 | Supervivencia de la coincidencia más larga | fr | Supervivencia del partido más largo | Indica la duración de supervivencia de un jugador en cualquier partido. | 4 | Oro total recolectado | es | Oro total recolectado | La jugadora recoge monedas mientras juega en un partido | 4 | Oro total recolectado | fr | Or total collecté | Le joueur collecte des pièces en jouant un match |
Planifica el esquema
Puedes enviar dos tipos de datos con la API de Game Stats: eventos flexibles del jugador y un evento predefinido para las estadísticas de progresión del jugador. En los siguientes ejemplos, se ilustra cómo se ven los eventos flexibles en varios tipos de juegos.
Eventos del reproductor flexibles
Los eventos de jugadores se definen por momentos distintos en el juego, finalizaciones de bucles de juego o hitos de progresión.
- Define eventos como momentos específicos dentro del juego, finalizaciones del bucle de juego o hitos de progresión:
- Completaciones del bucle de juego, como una partida o una carrera completadas
- Hitos de progresión, como el progreso de exploración de un área guardada o un nivel completado
- Agrega propiedades para proporcionar contexto sobre el evento y sus resultados, como el número de nivel, el tipo de partida, el tipo de arma, la cantidad de armas, los disparos a la cabeza, las monedas recolectadas, el resultado de la partida, el tiempo de vuelta o el tipo de automóvil.
- Envía eventos dentro de la sesión de juego en cuanto ocurran. Por ejemplo, envía un evento de finalización del bucle de juego inmediatamente después de que se complete el bucle.
Ejemplos
| Tipo de juego | Etiqueta del evento | Momento en el juego, finalización de evento de progresión o finalización de bucle de juego | Resultado | Características |
|---|---|---|---|---|
| Juego de habilidad mental indie de progresión lineal | chapter_completed | Finalización del evento de progresión | N/A | Número de capítulo, nombre del capítulo, cantidad de intentos, cantidad de pantallas, cantidad de movimientos y contenido del capítulo |
| screen_completed | Finalización del evento de progresión | Número de capítulo, nombre del capítulo, cantidad de intentos, cantidad de movimientos y contenido del capítulo | ||
| Carrera ininterrumpida en 3D | run_completed | Finalización del bucle de juego | Monedas recolectadas y puntuación | Duración de la carrera, monedas recolectadas con el jetpack, potenciador usado al inicio de la carrera, tablas de surf usadas, imanes usados, saltador usado, jetpack usado |
| RPG de acción de mundo abierto | areaExplorationProgress | Finalización del evento de progresión | Enemigos derrotados y pociones recolectadas | Número de área, nombre del área y porcentaje de progreso |
| questCompleted | Finalización del bucle de juego | N/A | Nombre de la misión | |
| weaponUnlocked | Momento en el juego | N/A | Nombre del arma y nivel del arma | |
| chestUnlocked | Momento en el juego | Mineral de mejora recolectado | ||
| Rompecabezas casual con metadatos decorativos | puzzleCompleted | Finalización del bucle de juego o del evento de progresión | Monedas y refuerzos obtenidos | Cantidad de movimientos, ¿se usó el regalo de Butler? Tipo de nivel, número de nivel, potenciadores de color usados y dinamitas usadas |
| cardsCollected | Momento en el juego | Tarjetas de 1 estrella, tarjetas de 2 estrellas, tarjetas de 3 estrellas y total de tarjetas | Número y nombre del álbum | |
| Carreras de arcade | raceCompleted | Finalización del bucle de juego | Rank, NOS used, race_time | Tipo de carrera, clasificación, car_used |
| carUpgraded | Momento en el juego | Característica del automóvil que se actualizó, nivel o valor anterior, nivel o valor nuevo | Tipo de auto y nivel actual del estacionamiento | |
| Juego de disparos de Battle Royale en tercera persona | matchCompleted | Finalización del bucle de juego | Eliminaciones, disparos a la cabeza, valor de honor | Tipo de concordancia, tiempo de supervivencia |
| Simulación de administración de deportes electrónicos | matchCompleted | Finalización del bucle de juego | Resultado, goles marcados, goles | Nombre del equipo rival y del equipo que juega |
| trainingCompleted | Momento en el juego | Drills done, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
Evento progressUpdate
Si tu juego tiene una mecánica de progresión principal, usa este evento para enviar el progreso actual del jugador. El evento tiene una propiedad predefinida llamada "currentProgress" de tipo INT o STRING. Envía el valor del progreso actual con esta propiedad, ya que es el único valor que aparece en la IU de estadísticas de juego del perfil de jugador.
Dado que los jugadores pueden comparar sus perfiles según el progreso actual en el juego, es importante que no haya demoras en la obtención del valor de progreso actual después de la primera integración. Para representar el progreso actual preciso a los jugadores, debes enviar el evento progressUpdate al comienzo de cada sesión de juego y cada vez que haya una actualización del progreso actual.
Ejemplos
| Tipo de juego | Propiedad currentProgress del evento `progressUpdate` |
|---|---|
| Juego de habilidad mental de progresión lineal | Número de capítulo o nivel actual |
| 3D Endless Runner | Puntuación alta y saldo actual de potenciadores |
| Rompecabezas casual | Número de nivel actual, cantidad de victorias en el primer intento, cantidad de áreas completadas y cantidad de colecciones completadas |
| Carreras de arcade | Número de nivel actual, saldo de la moneda |
| RPG de acción de mundo abierto | Rango actual del personaje y número de nivel actual |
| Juego de disparos en tercera persona | Número de nivel actual |
| Simulación de deportes electrónicos | Número de nivel de administrador, número de nivel de club |
Detalles de la integración
Los extremos de API y el SDK están disponibles para recibir comentarios anticipados y estarán disponibles de forma general a partir de julio de 2026. Ver cronograma
En esta sección, se muestra cómo crear eventos y enviarlos en las integraciones del cliente y del servidor.
Cuándo debes enviar datos
Los eventos flexibles representan acciones dentro del juego relacionadas con la finalización de bucles de juego o momentos específicos dentro del juego. Envía estos eventos en cuanto se produzcan. Por ejemplo, envía el evento de finalización del bucle de juego en cuanto se complete el bucle.
El objeto progressUpdate Event representa el nivel de progreso actual de un jugador.
Los datos de la estadística de progresión se deben enviar con este evento en las siguientes situaciones:
- Siempre que haya una actualización del progreso actual, envía el valor más reciente de inmediato.
- Cada vez que un jugador inicia el juego, para garantizar la presencia de esta estadística para un jugador en todo momento.
Rutas de integración
Existen dos rutas de integración: cliente y servidor a servidor.
Integración de servidor a servidor
Un extremo de API pública te permite enviar eventos en la carga útil de la solicitud con las siguientes configuraciones:
Parámetros de ruta
| Parámetro | Tipo de datos | Descripción |
|---|---|---|
| playerId | String | Es el ID de los PGS del jugador. |
Autorización y autenticación
Las llamadas a la API de servidor a servidor siguen los lineamientos estándar de acceso del servidor a los Servicios de juego de Play con OAuth 2.0. Las solicitudes deben incluir un token de portador autorizado con el alcance https://www.googleapis.com/auth/games.
Eventos flexibles: cuerpo de la solicitud
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: Cuerpo de la solicitud
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 }
Cuerpo de la respuesta
Si la operación se realiza correctamente, se muestra un estado HTTP 200 OK con un objeto JSON vacío.
Ejemplo de cuerpo de la solicitud
Evento flexible: 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 de 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 } } ] }
Integración del cliente
La integración del cliente estará disponible a través de los SDKs de Unity, Java y C++.
La integración del cliente para PlayerGameEvent implicaría que compiles el objeto de evento en Java o C#, según el SDK, en los puntos de activación y que los envíes con las funciones de carga que proporciona el SDK.
Del mismo modo, para el evento progressUpdate, registra el progreso actualizado con la propiedad currentProgress con propiedades definidas adicionales y envíalas con las funciones de carga que proporciona el SDK.
Eventos
Las integraciones del cliente para PlayerGameEvent son las siguientes:
Crea un evento de juego de Flexible Player
Java
// 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 ...
Unity
// 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 ...
C++
// 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);
}
Compila el evento de juego del reproductor progressUpdate
Java
// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
.addProperty("currentProgress", 52)
// Add other properties if needed
.build();
List events = new ArrayList<>();
// ... populate list ...
Unity
// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
.AddProperty("currentProgress", 52)
// Add other properties if needed
.Build();
var events = new List();
// ... populate list ...
C++
PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}
Grabar evento y subir
Java
// Buffers the event locally.
client.recordEvent(event);
// Buffers the events locally, (List version)
client.recordEvents(events);
// This submits the events to PGS
client.requestEventsUpload();
Unity
// 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();
C++
// 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);
Cronograma
| Fecha | Integración de la API de Game Stats | Configuración de Estadísticas de juego |
| Junio de 2026 |
|
No disponible |
| Julio de 2026 |
|
|
| Agosto de 2026 | N/A |
|
| Septiembre de 2026 | N/A |
|