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.
Etapas de integração
Envie dados usando a API Game Stats como eventos flexíveis 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
do 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:
- 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 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 corrida, 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 as diretrizes para arquivos CSV.
- Integração com a API Game Stats:envie dados brutos do jogador no formato declarado para eventos flexíveis 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 flexíveis 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 flexíveis e
evento
- 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
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 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 e como o jogador a conquista.
- Forneça um ícone exclusivo que represente a estatística inserindo o nome exato do arquivo de ícone no arquivo CSV.
- Forneça uma ordem de sequência para especificar a ordem em que um jogador veria as estatísticas no perfil de jogador
- 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
currentProgressfor 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.
- Arquivo CSV para estatísticas repetitivas:
Diretrizes para arquivos CSV de eventos
É possível importar eventos usando o arquivo PlayerGameEvent.csv.
| Nome do arquivo | Obrigatório ou opcional |
| PlayerGameEvent.csv | Obrigatório |
Formato PlayerGameEvent.csv
O CSV contém o evento declarado e as propriedades dele como valores separados por vírgula na seguinte ordem:
Event Name,Property Name,Property Type
Se você enviar o evento progressUpdate para o progressionStat, adicione uma linha para esse evento. Esse evento precisa conter pelo menos uma propriedade currentProgress do tipo INT ou STRING, além de outras propriedades que você queira enviar.
Exemplo de tabela
| Nome do evento | Nome da propriedade | Tipo de propriedade |
|---|---|---|
| matchCompleted | duration | DOUBLE |
| matchCompleted | mata | INT |
| matchCompleted | isWinner | BOOLEANO |
| matchCompleted | matchType | STRING (UTF-8) |
| itemCollected | coinsAmount | INT |
| itemCollected | weaponType | STRING (UTF-8) |
| progressUpdate | currentProgress | INT |
Diretrizes para arquivos ZIP de estatísticas
É possível importar estatísticas de uma só vez usando um arquivo ZIP. Consulte a tabela para saber os nomes exatos a serem usados:
| Nome do arquivo | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
RepetitiveStatsConfig.csv
|
Obrigatório | Metadados de muitos eventos. |
ProgressionStatConfig.csv
|
Obrigatório | Evento declarado e as propriedades dele. |
StatLocalizations.csv
|
Opcional | Fornece traduções para nomes e descrições de conquistas. |
| Arquivos de ícones | Obrigatório | Ícones nos formatos PNG, JPEG ou JPG de 512 x 512. |
Formato RepetitiveStatsConfig.csv
O CSV contém o evento declarado e as propriedades dele como valores separados por vírgula na seguinte ordem:
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
Se você não quiser usar a condição de filtro, deixe a célula em branco.
Exemplo de tabela
| ID da estatística | Nome do evento | Nome da propriedade | Agregação | Nome de exibição da estatística | Descrição da estatística | Propriedade de filtro (opcional) | Operador de filtro (opcional) | Valor do filtro (opcional) | É competitivo | minLimit | maxLimit | Nome do arquivo do ícone | Número de sequência | Boa direção de valor | unidade |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | matchCompleted | duration | MAX | Sobrevivência da maior correspondência | Isso indica o tempo de sobrevivência de um jogador em qualquer partida. | isWinner | = | TRUE | TRUE | 0 | 50 | stat1.png | 1 | Diminuindo | segundos |
| 2 | matchCompleted | isWinner | COUNT | Partidas ganhas | Isso indica o número de partidas que um jogador venceu. | isWinner | = | TRUE | TRUE | 0 | 50 | stat3.png | 2 | Aumentando | |
| 3 | matchCompleted | mata | SUM | Mortes em partidas individuais | Número de eliminações em partidas individuais | matchType | = | "1:1" | FALSO | stat4.png | 4 | Aumentando | |||
| 4 | itemCollected | coinsAmount | SUM | Total de ouro coletado | O jogador coleta moedas enquanto joga uma partida | weaponType | = | "espada" | FALSO | stat2.png | 3 | Aumentando |
Formato ProgressionStatConfig.csv
O CSV contém o evento declarado e as propriedades dele como valores separados por vírgula na seguinte ordem:
Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit
A estatística de progressão será mostrada como a primeira estatística de um jogador no perfil de jogador.
Exemplo de tabela
| ID da estatística | Nome de exibição da estatística | Descrição da estatística | Nome do arquivo do ícone | Boa direção de valor |
| 5 | Nível | Os jogadores acumulam XP jogando partidas e sobem de nível. | Level.png | aumentando |
Formato StatLocalizations.csv
O CSV contém o evento declarado e as propriedades dele como valores separados por vírgula na seguinte ordem:
Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description
Exemplo de tabela
| ID da estatística | Nome de exibição da estatística | Código do idioma | Nome da estatística localizada (UTF-8) | Descrição da estatística localizada (UTF-8) | 1 | Sobrevivência da maior correspondência | es | Supervivencia más larga en partidos | Esto denota el tiempo de supervivencia de una jugadora en cualquier partido. | 1 | Sobrevivência da maior correspondência | fr | Survie du match le plus long | Cela indique la durée de survie d'un joueur dans n'importe quel match. | 4 | Total de ouro coletado | es | Oro total recolectado | La jugadora recoge monedas mientras juega en un partido | 4 | Total de ouro coletado | fr | Ou total collecté | Le joueur collecte des pièces en jouant un match |
Planejar o esquema
É possível enviar dois tipos de dados usando a API Game Stats: eventos flexíveis do jogador e um evento predefinido para estatísticas de progressão do jogador. Os exemplos a seguir ilustram como os eventos flexíveis aparecem em vários tipos de jogos.
Eventos flexíveis 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.
- 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.
Exemplos
| Tipo de jogo | Rótulo do evento | Momento no jogo / Conclusão de evento de progressão / Conclusão de loop do jogo | Resultado | Características |
|---|---|---|---|---|
| Jogo de quebra-cabeça indie de progressão linear | chapter_completed | Conclusão do 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 do 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 em 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 do evento de progressão | Inimigos derrotados, poções coletadas | Número da área, nome da área, porcentagem de progresso |
| 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 aprimoramento coletado | ||
| Quebra-cabeça casual com metadados decorativos | puzzleCompleted | Conclusão do loop de jogo / Conclusão do evento de progressão | Moedas e 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 | Cards de 1 estrela, cards de 2 estrelas, cards de 3 estrelas, total de cards | Número do álbum, nome do álbum | |
| Corrida de arcade | raceCompleted | Conclusão do loop de jogo | Posiçã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 battle royale em terceira pessoa | matchCompleted | Conclusão do loop de jogo | Eliminações, headshots, valor de honra | Tipo de correspondência, 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 e do time que está jogando |
| trainingCompleted | Momento no jogo | Drills done, 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. Envie o valor do progresso atual usando essa propriedade, já que é o único valor que aparece na interface de estatísticas do jogo do perfil do jogador.
Como os jogadores podem comparar os perfis com base no 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.
Exemplos
| Tipo de jogo | Propriedade "currentProgress" do evento "progressUpdate" |
|---|---|
| Jogo de quebra-cabeça de progressão linear | Número do capítulo ou nível atual |
| Corrida infinita em 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 |
| 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 |
Detalhes da integração
Os endpoints da API e o SDK estão disponíveis para feedback antecipado e vão estar disponíveis para todos os usuários a partir de julho de 2026. Consulte cronograma
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 flexíveis 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:
- 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ública permite enviar eventos no payload da solicitação usando as seguintes configurações:
Parâmetros de caminho
| Parâmetro | Tipo de dado | Descrição |
|---|---|---|
| playerId | String | O ID do jogador no PGS. |
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 flexíveis: corpo da solicitação
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: 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 }
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 flexível: 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 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 } } ] }
Integração do lado do cliente
A integração do lado do cliente será disponibilizada usando SDKs do Unity, Java e C++.
A integração do lado do cliente para PlayerGameEvent envolve a criação do
objeto de evento em Java ou Csharp, dependendo do SDK, nos pontos de acionamento e
o envio deles usando as funções de upload fornecidas pelo SDK.
Da mesma forma, para o evento progressUpdate, registre o progresso atualizado usando a propriedade currentProgress com outras propriedades definidas e envie-as usando as funções de upload fornecidas pelo SDK.
Eventos
As integrações do lado do cliente para o PlayerGameEvent são:
Criar evento de jogo do player flexível
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);
}
Criar evento de jogo do player 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);
}
Gravar evento e fazer upload
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
| Data | Integração da API Game Stats | Configuração das estatísticas do jogo |
| Junho de 2026 |
|
Indisponível |
| Julho de 2026 |
|
|
| Agosto de 2026 | N/A |
|
| Setembro de 2026 | N/A |
|