Estatísticas da partida

As estatísticas do jogo são cumulativas e podem ser acessadas pelos jogadores no perfil de jogador. Com essas estatísticas, os jogadores podem acompanhar o progresso ao longo da vida, ver os melhores momentos e comparar com outros jogadores, além de usar recursos do Google Play, como missões, desafios sociais e muito mais no futuro.

As estatísticas do jogo precisam:

• Não exigir uma compra (por exemplo, comprar gemas), ou seja, não devem ser atualizados como resultado de uma compra no app.
• Não exigir a visualização de anúncios, ou seja, não atualizar como resultado da visualização de um anúncio.
• Não ser um uso genérico do jogo (por exemplo, abrir o jogo, usar as configurações).
• Não incluir dados pessoais e sensíveis do usuário, conforme definido na política do Google Play, incluindo IDs de usuário, senhas, localização precisa ou dados de saúde, ou qualquer conteúdo ofensivo, profano, sexualmente explícito, violento ou de ódio.
• Estar disponível para todos os usuários (por exemplo, não ser uma ação específica da equipe ou estar disponível apenas para usuários de um determinado nível ou limitado a liveops por tempo limitado etc.)

Etapas de integração

Envie dados usando a API de estatísticas do jogo como eventos do jogador para estatísticas repetitivas e um evento predefinido progressUpdate para a estatística de progressão. Você também precisará configurar a lógica para calcular as estatísticas que aparecem no perfil de jogador e as informações de exibição delas.

Os eventos do jogador representam momentos distintos no jogo, conclusões do loop do jogo ou marcos de progressão.

Um evento do jogador é definido e modelado da seguinte forma:

1. Um evento é representado por uma ação específica realizada pelo jogador, como concluir uma partida, terminar uma corrida, desbloquear um baú ou salvar o progresso em uma área.
2. Cada ação resulta em determinados resultados ou tem certas características que a definem. Eles são modelados como propriedades de evento que fornecem contexto sobre o evento e os resultados específicos dele (por exemplo, tipo de partida, moedas coletadas durante a partida, resultado da partida ou contagem de tiros na cabeça).

A integração consiste nas seguintes etapas:

• Declare o esquema de dados brutos:defina eventos do jogador usando um upload de CSV no Play Console. Consulte Criar eventos.
• Integração com a API de estatísticas do jogo:envie dados brutos do jogador no formato declarado para eventos do jogador e evento progressUpdate.
  • Envie todos os eventos definidos usando a integração do lado do cliente ou do servidor. Para mais informações, consulte exemplos de Eventos do player e evento progressUpdate.
• Fazer upload de um arquivo ZIP:forneça três arquivos CSV e todos os arquivos de imagem de ícone que definem cinco estatísticas repetitivas e um nível de progressão do jogador. Para mais informações, consulte as diretrizes para arquivos ZIP. Inclua os seguintes detalhes:
  • Arquivo CSV para estatísticas repetitivas:
    • Um ID exclusivo da estatística.
    • Especifique o marcador de evento a ser usado para o cálculo de estatísticas. Não é possível usar o marcador de evento progressUpdate aqui.
      • Especifique o rótulo da propriedade a ser usado para o cálculo de estatísticas. Precisa ser uma propriedade do evento especificado.
      • Especifique o tipo de agregação (SUM, MAX, MIN ou COUNT) para determinar como calcular a estatística no rótulo da propriedade selecionada.
      • Especifique uma condição de filtro opcional para calcular a lógica somente quando a condição for atendida. Defina a propriedade e o rótulo do evento, o operador (=, <, <=, >= ou >) e o valor do limite.
    • Inclua uma flag booleana para indicar se a estatística pode ser usada em recursos competitivos.
    • Se o recurso puder ser usado para recursos competitivos, os limites mínimos e máximos por hora para um jogador legítimo. Isso será usado para identificar jogadores que possam estar usando de forma indevida recursos como ligas e desafios sociais.
    • Forneça um nome de exibição exclusivo para a estatística que os jogadores veem.
    • Forneça um texto exclusivo que descreva a estatística. Essa descrição deve detalhar como o jogador a ganha e será mostrada aos jogadores na interface do perfil do jogador.
    • Forneça um ícone exclusivo que represente a estatística inserindo o nome exato do arquivo de ícone no arquivo CSV.
    • Forneça uma entrada opcional para indicar se um valor crescente ou decrescente é bom para o jogador. Essa entrada será usada para celebrar os movimentos do jogador.
    • Forneça uma unidade de medida opcional para a estatística, como km, milhas e segundos.
  • Arquivo CSV para estatística de progressão do jogador:
    • Forneça um nome de exibição exclusivo para a progressão do jogador que os jogadores veem.
    • Forneça um ícone exclusivo que represente a estatística.
    • Forneça uma descrição para a estatística de progressão.
    • Forneça uma entrada opcional para indicar se um valor crescente ou decrescente é bom para o jogador. Essa entrada será usada para celebrar os movimentos do jogador somente quando a propriedade currentProgress for do tipo INT.
    • Forneça uma unidade de medida opcional para a estatística, como km, milhas ou segundos.
  • Arquivo CSV para localização:forneça nomes de exibição localizados para todas as estatísticas.
    • Adicione uma linha para cada localização.
    • Use a string do nome de exibição da estatística, conforme adicionado no CSV anterior, para identificar de forma exclusiva a estatística em que a localização está sendo adicionada.
    • Especifique o idioma em uma lista de códigos.
    • Adicione a localização do nome de exibição no idioma especificado.
    • Adicione a localização da descrição da estatística no idioma especificado.

Planejar o esquema

É possível enviar dois tipos de dados usando a API Estatísticas do Jogo: eventos do jogador e um evento predefinido para estatísticas de progressão do jogador.

Os exemplos a seguir ilustram como os eventos do player aparecem em vários tipos de jogos:

Eventos do player

Os eventos do jogador são definidos por momentos distintos no jogo, conclusões de loop de jogo ou marcos de progressão.

• Defina eventos como momentos específicos no jogo, conclusões de loop de jogo ou marcos de progressão:
  • Conclusões do loop de jogo, como uma partida ou corrida concluída.
  • Marcos de progressão, como o progresso salvo da análise detalhada de uma área ou um nível concluído.
  • Como as estatísticas repetitivas precisam representar ações repetíveis de um jogador, os eventos definidos precisam estar associados à jogabilidade principal.
• Adicione propriedades para fornecer contexto sobre o evento e os resultados dele, como número do nível, tipo de partida, tipo de arma, número de armas, tiros na cabeça, moedas coletadas, resultado da partida, tempo da volta ou tipo de carro.
• Envie eventos na sessão de jogo assim que eles ocorrerem. Por exemplo, envie um evento de conclusão de loop de jogo imediatamente após a conclusão do loop.

progressUpdate evento

Se o jogo tiver uma mecânica de progressão principal, use esse evento para enviar o progresso atual do jogador. O evento tem uma propriedade predefinida chamada "currentProgress" do tipo INT ou STRING. É esperado que você envie o valor atual do progresso do jogador na mecânica de progressão principal usando essa propriedade. Se você usar esse evento, a propriedade predefinida "currentProgress" precisará estar presente, e uma estatística de progressão precisará ser definida usando essa propriedade.

É possível enviar o valor atual de outros sistemas de progressão no jogo, como lifetime highest score ou current coin balance, como outras propriedades desse evento.

Como os jogadores podem comparar os perfis pelo progresso atual no jogo, é importante que não haja atraso na obtenção do valor do progresso atual após a primeira integração. Para representar o progresso atual preciso aos jogadores, envie o evento progressUpdate no início de cada sessão de jogo e sempre que houver uma atualização no progresso atual.

Configurar suas estatísticas

Você precisa configurar as estatísticas de repetição e progressão definindo a lógica de computação e mostrando informações sobre cada uma delas. Confira abaixo exemplos de estatísticas de repetição de diferentes gêneros de jogos. Estatísticas repetitivas geralmente são atualizadas várias vezes para qualquer jogador em poucas sessões de jogo (3 a 4) e estão associadas ao loop principal do jogo.

Detalhes da integração

Os endpoints da API e o SDK estão disponíveis para feedback antecipado e vão estar em disponibilidade geral (GA) a partir de agosto de 2026. Consulte a linha do tempo

Esta seção mostra como criar eventos e enviá-los em integrações do lado do cliente e do servidor.

Quando enviar dados

Os eventos do jogador representam ações no jogo relacionadas a conclusões do loop de jogo ou momentos específicos no jogo. Envie esses eventos assim que eles ocorrerem. Por exemplo, envie o evento de conclusão do loop de jogo assim que ele for concluído.

O evento progressUpdate representa o nível de progresso atual de um jogador. Os dados da estatística de progressão devem ser enviados usando esse evento nas seguintes situações:

1. Sempre que houver uma atualização do progresso atual, envie o valor mais recente imediatamente.
2. Sempre que um jogador inicia o jogo para garantir a presença dessa estatística para um jogador em todos os momentos.

Caminhos de integração

Há dois caminhos de integração: cliente e servidor para servidor.

Integração de servidor para servidor

Com um endpoint de API pública, é possível enviar eventos no payload da solicitação usando as seguintes configurações:

Parâmetros de caminho

Autorização e autenticação

As chamadas de API de servidor para servidor seguem as diretrizes padrão de acesso do lado do servidor aos Serviços relacionados a jogos do Google Play usando o OAuth 2.0. As solicitações precisam incluir um token do portador autorizado com o escopo https://www.googleapis.com/auth/games.

Eventos: corpo da solicitação

A API de back-end tem limites rigorosos de validação estrutural:

• Tamanho do lote:no máximo 30 eventos por BatchRecordEventsRequest.
• Contagem de propriedades:no máximo 25 propriedades personalizadas por PlayerGameEvent.
• Limites de comprimento:nome do evento (máximo de 100 caracteres), chaves de propriedade (máximo de 100 caracteres) e valores de string de propriedade (máximo de 1.024 caracteres).
• ID do evento:precisa ser uma string UUID de 36 caracteres válida.
• Repetição e armazenamento em cache:evite armazenar em cache ou acumular eventos excessivos localmente se a API falhar, já que as repetições em lote que excederem 30 eventos serão rejeitadas. Sempre divida as novas tentativas para respeitar o limite de tamanho do lote.

BatchRecordEventsRequest

Veja 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 da solicitação

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 da resposta

Se a operação for bem-sucedida, vai retornar um status HTTP 200 OK com um objeto JSON vazio.

Exemplo de corpo da solicitação

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

Implementações do cliente

Para saber mais sobre a implementação do cliente de estatísticas do jogo na sua plataforma, consulte os recursos a seguir:

• Android
• Unity
• C++

Marcos