Estadísticas del partido

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 a los jugadores hacer un seguimiento de su progreso a lo largo del tiempo, ver los momentos destacados y compararse con otros jugadores, y potenciar las funciones de Google Play, como las misiones, los desafíos sociales y mucho más en el futuro.

• No deben requerir una compra (por ejemplo, comprar gemas), es decir, no deben actualizarse como resultado de ninguna compra directa desde la app.
• 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 del usuario, 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, profano, sexualmente explícito, violento o que incite al odio
• Estar disponible para todos los usuarios (por ejemplo, no ser una acción específica del equipo ni estar disponible solo para usuarios de un cierto nivel o limitarse a liveops por tiempo limitado, etc.)

Pasos para la integración

Envía datos con la API de Estadísticas de juego 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 gamer y su información de visualización.

Los eventos de jugadores representan momentos distintos en el juego, finalizaciones del bucle de juego o logros de progresión.

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. 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 Crea eventos.
• Integración con la API de Estadísticas de juego: 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 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 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 etiqueta de propiedad y 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 la obtiene el jugador y se les mostrará a los jugadores en la IU del perfil de jugador.
    • Proporciona un ícono único que represente la estadística ingresando el nombre de archivo exacto del ícono en el archivo CSV.
    • 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 el progreso 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 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 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.

Planifica el esquema

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

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

Eventos del reproductor

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
  • Dado que las estadísticas repetitivas deben representar realmente las acciones repetibles de un jugador, los eventos definidos deben asociarse con la jugabilidad 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 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.

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, la propiedad predefinida "currentProgress" debe estar presente y se debe definir una estadística de progresión con esta propiedad.

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

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 se actualice el progreso actual.

Cómo configurar tus estadísticas

Deberás configurar tus estadísticas repetitivas y de progresión definiendo la lógica de cálculo y la información de visualización de 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 muy pocas sesiones de juego (de 3 a 4) y están asociadas con el bucle de juego principal.

Detalles de la integración

Los extremos de API y el SDK están disponibles para recibir comentarios anticipados y tendrán disponibilidad general (DG) a partir de agosto 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 de jugador 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:

1. Siempre 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: cliente y servidor a servidor.

Integración de servidor a servidor

Un endpoint de API pública te permite enviar eventos en la carga útil de la solicitud con las siguientes configuraciones:

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

Eventos flexibles: 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
• Cantidad 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 UUID de 36 caracteres válida.
• Reintentos y almacenamiento en caché: Evita almacenar en caché o acumular eventos excesivos de forma local si falla la API, 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 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: 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 de 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

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

• Android
• Unity
• C++

Logros