Estadísticas del partido

Las Estadísticas de juego son estadísticas acumuladas 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 desde el principio, vean momentos destacados y se comparen con otros jugadores, además de impulsar funciones de Google Play, como misiones, desafíos sociales y mucho más en el futuro.

Las estadísticas de juego deben cumplir con los siguientes requisitos:

• No requerir una compra (por ejemplo, comprar gemas), es decir, no deben actualizarse como resultado de ninguna compra de IAP
• No deben requerir que se miren anuncios, es decir, no deben actualizarse como resultado de mirar un anuncio.
• No debe ser un uso genérico del juego (por ejemplo, abrir el juego o usar la configuración).
• No incluir datos personales y sensibles de los usuarios, según se definen en la política de Play, incluidos los IDs de usuario, las contraseñas, la ubicación precisa o los datos de salud, ni ningún contenido ofensivo, obsceno, sexualmente explícito, violento o que incite al odio.
• Estar disponible para todos los usuarios (por ejemplo, no debe ser una acción específica de un equipo, estar disponible solo para usuarios de un nivel determinado ni limitarse a eventos de LiveOps por tiempo limitado, etc.)

En la imagen, se muestran las estadísticas de juego en el perfil de gamer en la pestaña Tú. Esta interfaz de usuario (IU) de la pestaña Tú solo está disponible para realizar pruebas. La IU de Estadísticas de juego estará disponible en septiembre de 2026.

Tipo de agregación

El tipo de agregación le indica a Google Play cómo calcular una estadística a partir de los valores por evento que envías:

• SUM: Se usa para las estadísticas acumulativas (como el total de monedas recolectadas o el total de daño infligido). El juego debe enviar el importe discreto ganado durante cada instancia del evento.
• COUNT: Se usa para las estadísticas que representan la cantidad de veces que se produce un evento (como partidas jugadas o partidas ganadas). El juego debe enviar las instancias de ocurrencia de eventos discretos.
• MAX: Se usa solo para logros máximos de un solo caso (como la puntuación más alta en una sola carrera, la racha de combos máxima o el daño más alto en una sola partida). No uses MAX como solución alternativa para mostrar los totales del ciclo de vida a partir de valores de ejecución calculados previamente.

Requisito de implementación fundamental para las estadísticas repetitivas

• Envía valores por evento: Para cada evento, envía solo lo que sucedió en ese evento, como las monedas recopiladas en una sola ejecución. Luego, establece un tipo de agregación, como SUM o COUNT, en la configuración de estadísticas. Esto garantiza que las estadísticas repetitivas se puedan reutilizar en las mecánicas de participación y permite que Google Play cree las experiencias de jugador adecuadas.
• No envíes totales del ciclo de vida: Por ejemplo, no hagas un seguimiento de la cantidad total de monedas que un jugador haya recolectado en el cliente o servidor de tu juego y envíes ese total con la agregación MAX. Esas estadísticas se seguirán mostrando en la IU del perfil de gamer, pero Google Play no podrá usarlas para potenciar funciones de recompensas, como ligas, misiones y sprints, para mejorar la experiencia de los jugadores y generar un impacto en tu juego.

Para obtener instrucciones y ejemplos sobre el modelado correcto de eventos, consulta Eventos de jugadores y Cómo configurar tus estadísticas.

Pasos para la integración

Envía datos con la API de Game Stats como eventos de jugador para las estadísticas repetitivas y un evento predefinido progressUpdate para la estadística de progreso. También deberás configurar la lógica para calcular las estadísticas que aparecerían en el perfil de gamer y su información de visualización.

Los eventos de jugador representan distintos momentos del juego, finalizaciones de bucles de juego o hitos de progreso.

Un evento de jugador se define y modela de la siguiente manera:

1. 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.
2. Cada acción genera ciertos resultados o tiene ciertas características que la definen. Estas se modelan como propiedades de eventos que proporcionan contexto sobre el evento y sus resultados específicos (por ejemplo, el tipo de partida, las monedas recolectadas durante esa carrera, el resultado de la partida o el 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 subiendo un archivo CSV en Play Console. Consulta Cómo crear eventos.
• Integración con la API de Estadísticas de juego: Envía datos sin procesar de los jugadores en el formato declarado para los eventos de jugador 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 del reproductor y el evento progressUpdate.
• 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 progreso 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 de evento que se usará para el cálculo de estadísticas. No puedes usar la etiqueta de evento progressUpdate aquí.
      • 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 en funciones competitivas.
    • Si la función se puede usar para funciones competitivas, se deben establecer límites mínimos y máximos por hora para un jugador genuino. Esto nos servirá para 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 ven los jugadores.
    • Proporciona un texto único que describa la estadística. Esta descripción debe proporcionar detalles sobre cómo el jugador la obtiene y se mostrará a los jugadores en la IU del perfil de gamer.
    • Proporciona un ícono único que represente la estadística ingresando el nombre exacto del archivo de ícono en el archivo CSV.
    • Proporciona una entrada opcional que indique 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 progreso del jugador:
    • Proporciona un nombre visible único para la progresión del jugador que los jugadores ven.
    • Proporciona un ícono único que represente la estadística.
    • Proporciona una descripción para la estadística de progreso.
    • Proporciona una entrada opcional que indique si un valor creciente o decreciente es bueno para el jugador. Esta entrada se usará para celebrar los movimientos de los jugadores solo cuando la propiedad currentProgress sea 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 como se agregó en el archivo CSV anterior para identificar de forma inequívoca la estadística a la que se agrega la localización.
    • Especifica el idioma de 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.

Planifica el esquema

Puedes enviar dos tipos de datos con la API de Game Stats: eventos de jugadores y un evento predefinido para las estadísticas de progreso de los jugadores.

En los siguientes ejemplos, se muestra cómo se ven los eventos de jugador en varios tipos de juegos:

Eventos del jugador

Los eventos de jugador se definen por momentos específicos del juego, finalizaciones de bucles de juego o hitos de progreso.

• Define eventos como momentos específicos del juego, finalizaciones de bucles de juego o hitos de progreso:
  • Finalizaciones de bucles de juego, como una partida o una carrera completadas
  • Hitos de progreso, como el progreso de exploración de un área guardada o un nivel completado
  • Dado que las estadísticas repetitivas deben representar de forma fidedigna las acciones repetibles de un jugador, los eventos definidos deben estar asociados con la experiencia de juego principal.
• 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 auto.
• 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.

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. Se espera que envíes el valor actual del progreso del jugador en la mecánica de progresión principal con esta propiedad. Si usas este evento, debe estar presente la propiedad predefinida "currentProgress" y se debe definir una estadística de progresión con esta propiedad.

Puedes enviar el valor actual de otros sistemas de progresión de tu juego, como lifetime highest score o current coin balance, como otras propiedades de este evento.

Como 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, así como cada vez que haya una actualización del progreso actual.

Configura tus estadísticas

Deberás configurar tus estadísticas repetitivas y de progreso definiendo la lógica de cálculo y mostrando información sobre cada estadística. A continuación, se incluyen ejemplos de estadísticas repetitivas de diferentes géneros de juegos. Las estadísticas repetitivas suelen ser estadísticas que se actualizan de forma reiterada para cualquier jugador en unas pocas (3 o 4) sesiones de juego y se asocian con el bucle de juego principal.

Para saber cuándo usar SUM, COUNT o MAX, consulta Elige el tipo de agregación adecuado.

Detalles de la integración

En esta sección, se muestra cómo crear eventos y enviarlos en integraciones del cliente y del servidor.

Cuándo debes enviar datos

Los eventos de jugador representan acciones en el juego relacionadas con la finalización de bucles de juego o momentos específicos en el 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 evento progressUpdate representa el nivel de progreso actual de un jugador. Los datos de la estadística de progreso se deben enviar con este evento en las siguientes situaciones:

1. Cada vez que haya una actualización del progreso actual, envía el valor más reciente de inmediato.
2. 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: de cliente y de servidor a servidor.

Integración de servidor a servidor

Un extremo de API público te permite enviar eventos en la carga útil de la solicitud con las siguientes opciones de configuración:

Solicitud HTTP

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

Parámetros de ruta

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 Play Games con OAuth 2.0. Las solicitudes deben incluir un token del portador autorizado con el permiso https://www.googleapis.com/auth/games.

Eventos: Cuerpo de la solicitud

La API de backend tiene límites estrictos de validación estructural:

• Tamaño del lote: Un máximo de 30 eventos por BatchRecordEventsRequest.
• Recuento de propiedades: Un máximo de 25 propiedades personalizadas por PlayerGameEvent.
• Límites de longitud: Nombre del evento (máx. 100 caracteres), claves de propiedad (máx. 100 caracteres) y valores de cadena de propiedad (máx. 1,024 caracteres).
• ID del evento: Debe ser una cadena de UUID de 36 caracteres válida.
• Reintentos y almacenamiento en caché: Evita almacenar en caché o acumular demasiados eventos de forma local si la API falla, ya que se rechazarán los reintentos por lotes que superen los 30 eventos. Siempre divide los reintentos en fragmentos para respetar el límite de tamaño del lote.

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: 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 // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

Cuerpo de la respuesta

Si se ejecuta correctamente, devuelve un estado HTTP 200 OK con un objeto JSON vacío.

Ejemplo de cuerpo de la solicitud

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

Implementaciones de clientes

Si quieres obtener información sobre la implementación del cliente de Estadísticas de juego para tu plataforma, consulta los siguientes recursos:

• Android
• Unity
• C++

Logros