As estatísticas do jogo são cumulativas e podem ser vistas pelos usuários no perfil de jogador. Com elas, os jogadores podem acompanhar o progresso ao longo do tempo, ver momentos de destaque e comparar o progresso uns com os outros. Além disso, poderão ativar recursos do Google Play, como missões, desafios entre jogadores e muito mais no futuro.
As estatísticas do jogo precisam:
- Não exigir uma compra (por exemplo, comprar joias), ou seja, eles não devem ser atualizados como resultado de uma compra no app.
- Não exigir que o usuário assista 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 pela 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 incitação ao ódio.
- Estar disponível para todos os usuários (por exemplo, não ser uma ação específica de uma equipe ou disponível apenas para usuários de um determinado nível ou limitada a operações em tempo real etc.)
A imagem mostra as estatísticas do jogo no perfil de jogador.
Tipo de agregação
O tipo de agregação informa ao Google Play como calcular uma estatística com base nos valores por evento que você envia:
- SUM: use para estatísticas cumulativas (como total de moedas coletadas, total de dano causado). O jogo precisa enviar o valor discreto ganho durante cada instância de evento.
- COUNT: use para estatísticas que representam o número de ocorrências de um evento, como jogos jogados ou vencidos. O jogo precisa enviar as instâncias de ocorrência de eventos discretos.
- MAX: use apenas para conquistas de pico de ocorrência única, como a pontuação mais alta em uma única corrida, a sequência máxima de combos ou o maior dano em uma única partida. Não use MAX como uma solução alternativa para exibir totais de ciclo de vida de valores de execução pré-calculados.
Requisito de implementação crítico para estatísticas repetitivas
- Enviar valores por evento: para cada evento, envie apenas o que aconteceu nele, como as moedas coletadas em uma única corrida. Em seguida, defina um tipo de agregação, como SUM ou COUNT, na configuração da estatística. Isso garante que as estatísticas repetitivas sejam reutilizáveis em todas as mecânicas de engajamento e permite que o Google Play crie as experiências certas para os jogadores.
- Não envie totais de vida útil: por exemplo, não acompanhe o total de moedas que um jogador já coletou no cliente ou servidor do jogo e envie esse total com a agregação MAX. Essas estatísticas vão continuar aparecendo na interface do perfil de jogador, mas o Google Play não poderá usá-las para ativar recursos de recompensa, como ligas, missões e sprints, que melhoram a experiência do jogador e geram impacto para o jogo.
Para instruções e exemplos sobre a modelagem correta de eventos, consulte Eventos do jogador e Configurar suas estatísticas.
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 apareceriam no perfil de jogador
e as informações de exibição.
Os eventos do jogador representam momentos distintos no jogo, conclusões de loops de jogo ou marcos de progressão.
Um evento de jogador é definido e modelado da seguinte maneira:
- 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.
- Cada ação resulta em determinados resultados ou tem determinadas características que a definem. Elas são modeladas como propriedades de evento que fornecem contexto sobre o evento e os resultados específicos (por exemplo, tipo de partida, moedas coletadas durante a corrida, resultado da partida ou contagem de tiros na cabeça).
A integração consiste nas seguintes etapas:
- Declarar o esquema de dados brutos: defina os 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 ações do jogador e o 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
do 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
do evento
- Fazer upload de um arquivo ZIP: envie 3 arquivos CSV e todos os arquivos de imagem de ícone que
definem 5 estatísticas repetitivas e 1 nível de progressão do jogador.
Para mais informações, consulte as diretrizes para arquivos ZIP.
Incluindo os seguintes detalhes:
- Arquivo CSV para estatísticas repetitivas:
- Um ID exclusivo da estatística.
- Especifique o rótulo do evento a ser usado para o cálculo de estatísticas. Não é possível usar o rótulo de evento
progressUpdateaqui.- 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 limite.
- Inclua uma flag booleana para indicar se a estatística pode ser usada para recursos competitivos.
- Se o recurso puder ser usado para recursos competitivos, os limites mínimos e máximos por hora para um jogador genuíno. Isso será usado para identificar jogadores que possam estar fazendo uso indevido ao participar de recursos como ligas e desafios sociais.
- Dê 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 precisa fornecer detalhes sobre como o jogador a ganha e será mostrada aos jogadores na interface do perfil de 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 que indique se um valor crescente ou decrescente é bom para o jogador. Essa entrada será usada para comemorar os movimentos do jogador.
- Forneça uma unidade de medida opcional para a estatística, como km, milhas e segundos.
- Arquivo CSV para estatísticas 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 que indique se um valor crescente ou decrescente é bom para o jogador. Essa entrada será usada para
comemorar os movimentos do jogador somente quando a propriedade
currentProgressfor do tipo INT. - Forneça uma unidade de medida opcional para a estatística, como km, milhas, 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 de idioma.
- 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.
- Arquivo CSV para estatísticas repetitivas:
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 de jogador aparecem em vários tipos de jogos:
Eventos de player
Os eventos do jogador são definidos por momentos distintos no jogo, conclusões de loops de jogo ou marcos de progressão.
- Defina eventos como momentos específicos no jogo, conclusões de loops de jogo ou
marcos de progresso:
- Conclusões de loops de jogo, como uma partida ou corrida concluída.
- Marcos de progressão, como o progresso salvo da exploração de uma área ou um nível concluído.
- Como as estatísticas repetitivas devem 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 o número do nível, o tipo de partida, o tipo de arma, o número de armas, os tiros na cabeça, as moedas coletadas, o resultado da partida, o tempo de volta ou o 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 o término do loop.
Exemplos
| Tipo de jogo | Rótulo do evento | Momento no jogo / Conclusão de evento de progressão / Conclusão de loop de jogo | Resultado | Características |
|---|---|---|---|---|
| Jogo indie de quebra-cabeça com progressão linear | chapter_completed | Conclusão de evento de progressão | N/A | Número do capítulo, nome do capítulo, número de tentativas, número de telas, número de movimentos, conteúdo do capítulo |
| screen_completed | Conclusão de evento de progressão | Número do capítulo, nome do capítulo, número de tentativas, número de movimentos, conteúdo do capítulo | ||
| Corrida infinita 3D | run_completed | Conclusão do loop de jogo | Moedas coletadas, pontuação | Duração da corrida, moedas coletadas com o jetpack, booster usado no início da corrida, pranchas de surf usadas, ímãs usados, jumper usado, jetpack usado |
| RPG de ação de mundo aberto | areaExplorationProgress | Conclusão de evento de progressão | Inimigos derrotados, poções coletadas | Número da área, nome da área, progresso percentual |
| questCompleted | Conclusão do loop de jogo | N/A | Nome da missão | |
| weaponUnlocked | Momento no jogo | N/A | Nome da arma, nível da arma | |
| chestUnlocked | Momento no jogo | Minério de melhoria coletado | ||
| Quebra-cabeça casual com meta decorativa | puzzleCompleted | Conclusão do loop de jogo / Conclusão do evento de progressão | Moedas coletadas, boosters coletados | Número de movimentos, O presente do mordomo foi usado?, Tipo de nível, número do nível, boosters de cor usados, dinamites usadas |
| cardsCollected | Momento no jogo | Cartas de 1 estrela, cartas de 2 estrelas, cartas de 3 estrelas, total de cartas | Número do álbum, nome do álbum | |
| Corrida de arcade | raceCompleted | Conclusão do loop de jogo | Classificação, NOS usado, race_time | Tipo de corrida, classificação, carro usado |
| carUpgraded | Momento no jogo | Característica do carro que foi atualizada, nível/valor antigo, nível/valor novo | Tipo de carro, nível atual da garagem | |
| Jogo de tiro em terceira pessoa Battle Royale | matchCompleted | Conclusão do loop de jogo | Eliminações, tiros na cabeça, valor de honra | Tipo de partida, tempo de sobrevivência |
| Simulação de gerenciamento de eSports | matchCompleted | Conclusão do loop de jogo | Resultado, gols marcados, gols | Nome do time adversário, nome do time que está jogando |
| trainingCompleted | Momento no jogo | Treinos concluídos, teamplay_form_attack, teamplay_form_defense, teamplay_form_possession, teamplay_form_condition |
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.
Você pode enviar o valor atual para outros sistemas de progressão no seu 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 de progresso
atual após a primeira integração. Para representar o progresso atual
com precisão para os jogadores, envie o evento progressUpdate no início de
cada sessão de jogo e sempre que houver uma atualização no progresso
atual.
Exemplos
| Tipo de jogo | Propriedade currentProgress do evento progressUpdate |
|---|---|
| Jogo de quebra-cabeça com progressão linear | Número do capítulo ou nível atual |
| Corrida infinita 3D | Maior pontuação, saldo atual de boosters |
| Quebra-cabeça casual | Número do nível atual, contagem de vitórias na primeira tentativa, contagem de áreas concluídas, número de coleções concluídas |
| Corrida de arcade | Número do nível atual, saldo da moeda |
| RPG de ação de mundo aberto | Classificação atual do personagem, número do nível atual |
| Jogo de tiro em terceira pessoa | Número do nível atual |
| Simulação de eSports | Número do nível de gerente, número do nível do clube |
Configurar as estatísticas
Você precisa configurar as estatísticas repetitivas e de progressão definindo a lógica de cálculo e as informações de exibição de cada estatística. Confira abaixo exemplos de estatísticas repetitivas de diferentes gêneros de jogos. As estatísticas repetitivas geralmente são atualizadas repetidamente para qualquer jogador em poucas (3 a 4) sessões de jogo e estão associadas ao loop de jogo principal.
Para saber quando usar SUM, COUNT ou MAX, consulte Escolher o tipo de agregação certo.
| Nome do jogo | Nome de exibição da estatística do jogo | Propriedade do evento | Lógica de cálculo [aggregation] | Filtrar |
|---|---|---|---|---|
| Corrida infinita em 3D | Execuções concluídas | Qualquer propriedade do evento run_completed | Contagem | Todos os valores [sem filtro] |
| Moedas coletadas | Propriedade coins_collected do evento run_completed | Soma | N/A | |
| Chaves coletadas | Propriedade keys_collected do evento run_completed | Soma | N/A | |
| Pontuação mais alta da corrida | Propriedade de pontuação do evento run_completed | Máx. | N/A | |
| Execuções com muitas moedas concluídas | Propriedade coins_collected do evento run_completed | Contagem | Valor > 5000 | |
| Jogo de quebra-cabeça com progressão linear | Capítulos concluídos | Qualquer propriedade do evento chapter_completed | Contagem | Todos os valores [sem filtro] |
| Telas concluídas | Qualquer propriedade do evento screen_completed | Contagem | Todos os valores [sem filtro] | |
| Capítulos concluídos na primeira tentativa | Propriedade num_try do evento chapter_completed | Contagem | Num_try = 1 | |
| Telas concluídas na primeira tentativa | Propriedade num_try do evento screen_completed | Contagem | Num_try = 1 | |
| RPG de ação de mundo aberto | Quests concluídas | Qualquer propriedade do evento quest_completed | Contagem | Todos os valores [sem filtro] |
| Áreas exploradas | Propriedade perc_progress do evento area_exploration_progress | Contagem | Valor = 100 | |
| Espadas desbloqueadas | Propriedade weapon_type do evento weapon_unlocked | Contagem | Valor = "sword" | |
| Inimigos derrotados | Propriedade Enemies_defeated do evento area_exploration_progress | Soma | N/A | |
| Poções de vida coletadas | Propriedade enhancement_ores do evento chest_unlocked | Soma | N/A | |
| Quebra-cabeça casual | Níveis concluídos | Qualquer propriedade do evento level_completed | Contagem | Todos os valores [sem filtro] |
| Níveis concluídos na primeira tentativa | Propriedade num_try do evento level_completed | Contagem | Valor = 1 | |
| Intensificadores de cor usados | Propriedade Color_booster_used do evento level_completed | Soma | N/A | |
| Bombas usadas | Propriedade Bomb_booster_used do evento level_completed | Soma | N/A | |
| Cartas coletadas | Propriedade total_cards do evento cards_collected | Soma | N/A | |
| Corrida de arcade | Competições vencidas | Propriedade de classificação do evento race_completed | Contagem | Valor = 1 |
| Corrida mais rápida | Propriedade race_time do evento race_completed | Min | N/A | |
| NOS usado | Propriedade NOS_used do evento race_completed | Soma | N/A | |
| Corridas concluídas com o Mustang | Propriedade car_type do evento race_completed | Contagem | Valor = "Mustang" | |
| Upgrades de carro | Qualquer propriedade do evento car_upgraded | Contagem | Todos os valores [sem filtro] | |
| Jogo de tiro em terceira pessoa Battle Royale | Partidas vencidas | Qualquer propriedade do evento match_completed | Contagem | Match_result = TRUE |
| Total de eliminações | Propriedade de eliminações do evento match_completed | Soma | N/A | |
| Maior tempo de sobrevivência | Propriedade survival_time do evento match_completed | Máx. | N/A | |
| Total de fotos de rosto | Propriedade headshots do evento match_completed | Soma | N/A | |
| Valor total da habilidade | Propriedade skill_value do evento match_completed | Soma | N/A | |
| Simulação de gerenciamento de eSports | Partidas vencidas | Propriedade de resultado do evento match_completed | Contagem | Result = "Won" |
| Total de gols marcados | Propriedade goals_scored do evento match_completed | Soma | N/A | |
| Partidas difíceis vencidas | Propriedade de resultado do evento hard_match_completed | Contagem | Result = "Won" | |
| Vitória com maior saldo de gols | Propriedade goal_difference do evento match_completed | Máx. | Result = "Won" | |
| Total de exercícios de treinamento | Propriedade drills_done do evento training_completed | Soma | N/A | |
| Total de treinamentos concluídos | Qualquer propriedade do evento training_completed | Contagem | N/A |
Detalhes da integração
Nesta seção, mostramos 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 à conclusão de loops de jogo ou a 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 terminar.
O evento progressUpdate representa o nível de progresso atual de um jogador.
Os dados da estatística de progressão precisam ser enviados usando esse evento nas seguintes
situações:
- Sempre que houver uma atualização no progresso atual, envie o valor mais recente imediatamente.
- 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
Um endpoint de API público permite enviar eventos no payload da solicitação usando as seguintes configurações:
Solicitação HTTP
POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats:
batchRecordEvents
Parâmetros de caminho
| Parâmetro | Tipo de dado | Descrição |
|---|---|---|
| playerId | String | O ID dos PGS do jogador. |
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 rígidos 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 tamanho: 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 válida de 36 caracteres.
- Nova tentativa e armazenamento em cache: evite armazenar em cache ou acumular eventos excessivos localmente se a API falhar, já que as novas tentativas em lote que excederem 30 eventos serão rejeitadas. Sempre divida as novas tentativas em blocos 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 for bem-sucedido, retorna 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 seguintes recursos: