Este documento explica como integrar as estatísticas do jogo ao seu jogo usando o Google Play Console. Ele aborda os formatos essenciais de arquivos CSV e ZIP e descreve como criá-los, importá-los e gerenciá-los.
Criar ou importar eventos
Há duas maneiras de adicionar eventos usando o Google Play Console:
- Criar um evento: adicione um evento por vez.
- Importar eventos: importe vários eventos.
Criar um evento
Para criar um evento para um jogo, siga estas etapas:
- No Google Play Console, selecione um jogo.
- Na página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo), selecione Adicionar um evento > Criar um evento.
- Na página Criar um evento, preencha o formulário.
- Clique em Salvar alterações.
Importar eventos
Para adicionar vários eventos ao jogo de uma só vez, siga estas etapas:
- Crie o arquivo CSV de eventos PlayerGameEvent.csv.
- No Google Play Console, selecione um jogo.
- Na página Serviços do Google Play Games – Estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo), selecione Adicionar um evento > Importar por CSV.
- Na página Configuração de eventos, solte o arquivo CSV para fazer upload.
- Depois de criar um evento, configure as estatísticas.
Criar ou importar estatísticas
Há duas maneiras de adicionar estatísticas pela primeira vez usando o Google Play Console:
- Criar uma estatística: adicione uma estatística por vez.
- Importar estatísticas: importe várias estatísticas.
Criar uma estatística
Para criar uma estatística para um jogo, siga estas etapas:
- No Google Play Console, selecione um jogo.
- Na página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo), selecione Adicionar uma estatística > Criar uma estatística.
- Na página Criar uma estatística, preencha o formulário.
- Clique em Salvar alterações.
- Depois de criar uma estatística, publique o jogo.
Estatísticas de importação
Para importar estatísticas, siga estas etapas:
- Crie o arquivo ZIP com estatísticas, localizações e arquivos de ícones de acordo com as diretrizes de arquivos ZIP para estatísticas.
- No Google Play Console, selecione um jogo.
- Na página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo), selecione Adicionar uma estatística > Importar via ZIP.
- Na página Configuração das estatísticas do jogo, solte o arquivo ZIP para fazer upload.
- Depois de fazer upload de todas as estatísticas, publique o jogo.
Testar estatísticas do jogo
Para verificar se as estatísticas do jogo funcionam como esperado, siga as etapas para testá-las:
- Abra o app Google Play Store.
- Faça login no seu perfil do Play Games no app Google Play Store.
- Confira as estatísticas do jogo no seu perfil de jogador.
Ver os registros no dispositivo
Para verificar se as estatísticas do jogo funcionam conforme o esperado, ative os registros no dispositivo:
Ative a depuração do adb no seu dispositivo e execute os comandos abaixo em um terminal:
adb shell setprop log.tag.Games INFO adb logcat -s "PlayGamesServices[GameStatsAgent]:I"
Verifique se uma mensagem de registro de sucesso é exibida, como mostrado no exemplo a seguir:
Successfully uploaded batch of X events.
Observação: como a API é compatível com uploads parciais, esse registro de informações indica que o lote foi processado. Se algum evento individual no lote falhar na validação do esquema, um registro de erro vai preceder essa mensagem.
Se algum evento enviado falhar na validação, você vai receber uma mensagem de erro detalhando a falha:
BatchRecordEvents validation failed for X event(s): ...
Publicar as estatísticas do jogo
Depois de concluir os testes, publique o jogo. Todos os eventos e estatísticas do jogo são publicados com ele.
Para publicar, siga estas etapas:
- No Google Play Console, selecione um jogo.
- Na página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo), clique em Revisar e publicar.
- Na página Serviços do Google Play Games: publicação (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Publicação), analise as ações e corrija os problemas.
- Clique em Publicar. Todas as suas estatísticas do jogo foram publicadas.
Editar estatísticas do jogo
Se você já tem estatísticas do jogo e quer editá-las:
- No Google Play Console, selecione um jogo.
- Acesse a página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo).
- Para editar um evento:
- Na seção Configuração de eventos, selecione um evento.
- É possível adicionar ou excluir propriedades de evento.
- Não é possível editar o Nome do evento.
- Clique em Salvar alterações.
- Para editar uma estatística:
- Na seção Configuração das estatísticas do jogo, selecione uma estatística.
- É possível editar os campos Nome da estatística, Descrição da estatística e Nome do arquivo do ícone.
- Não é possível editar o ID da estatística nem a Direção da progressão. Unidade de estatística e Detalhes do evento associado.
- Clique em Salvar alterações.
- Na página serviços do Google Play Games - Estatísticas do jogo, a estatística editada está no status Disponível para testadores.
- Depois de testar a estatística, clique em Revisar e publicar. Assim, seu jogo será republicado com todas as estatísticas atualizadas.
Excluir estatísticas do jogo
Depois que as estatísticas do jogo forem publicadas, elas não poderão ser excluídas.
É possível excluir um evento ou uma estatística com o status Disponível para testadores.
- No Google Play Console, selecione um jogo.
- Acesse a página Serviços do Google Play Games: estatísticas do jogo (Aumentar número de usuários > Serviços do Google Play Games > Configuração e gerenciamento > Estatísticas do jogo).
- Para excluir um evento:
- Na seção Configuração de eventos, selecione um evento.
- Clique em Excluir evento.
- Para excluir uma estatística:
- Na configuração das estatísticas do jogo, selecione a estatística que você quer excluir.
- Clique em Excluir estatística do jogo.
Diretrizes para arquivos CSV de eventos
A primeira linha do arquivo CSV é uma linha de cabeçalho. É preciso importar eventos usando o
arquivo CSV de eventos, por exemplo, PlayerGameEvent.csv.
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 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.
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
| Nome do evento | Obrigatório | Máximo de 50 caracteres Precisa conter apenas letras, números e sublinhados. Se o nome do evento especial |
| Nome da propriedade | Obrigatório | Máximo de 50 caracteres Precisa conter apenas letras, números e sublinhados. Exclusivo por evento: os nomes das propriedades precisam ser exclusivos no mesmo evento. Não use as seguintes palavras-chave reservadas: |
| Tipo de propriedade | Obrigatório | String de tipo enumerado que diferencia maiúsculas de minúsculas e corresponde a um dos tipos de dados compatíveis:
INT64, DOUBLE, STRING, BOOL
|
Requisitos do arquivo PlayerGameEvent.csv:
- O arquivo aceita no máximo 20 nomes de eventos exclusivos, com até 20 propriedades por evento.
- O conteúdo do arquivo não pode estar vazio e precisa ter pelo menos uma linha.
Exemplo de tabela
| Nome do evento | Nome da propriedade | Tipo de propriedade |
|---|---|---|
| matchCompleted | duração | DOUBLE |
| matchCompleted | mortes | INT64 |
| matchCompleted | isWinner | BOOL |
| matchCompleted | matchType | STRING |
| itemCollected | coinsAmount | INT64 |
| itemCollected | weaponType | STRING |
| progressUpdate | currentProgress | INT64 |
Diretrizes de arquivos ZIP para estatísticas
É possível importar estatísticas de uma só vez usando um arquivo ZIP. Consulte a tabela para saber os nomes exatos de arquivo a serem usados no seu arquivo ZIP:
| Nome do arquivo | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
RepetitiveStatsConfig.csv
|
Obrigatório | Uma estatística repetitiva representa ações que ocorrem regularmente no jogo e são realizadas pelos jogadores. |
ProgressionStatConfig.csv
|
Obrigatório | Uma estatística de progressão representa o progresso de um jogador em um jogo. |
StatLocalizations.csv
|
Opcional | Fornece traduções para nomes e descrições de estatísticas do jogo. |
| Arquivos de ícones | Obrigatório | Ícones nos formatos PNG, JPEG ou JPG de 512 x 512. |
O arquivo ZIP precisa atender aos seguintes requisitos:
- Limite de tamanho do arquivo ZIP: o tamanho total máximo descompactado é de 10 MB.
- Máximo de arquivos: no máximo 53 arquivos (3 CSV e 50 ícones) no arquivo ZIP.
- Limite máximo de estatísticas combinadas: no máximo 50 estatísticas no total em
ProgressionStatConfig.csveRepetitiveStatsConfig.csv. - Arquivos CSV compatíveis:
ProgressionStatConfig.csv,RepetitiveStatsConfig.csveStatLocalizations.csv(opcional). Se você quiser fazer upload apenas de estatísticas de progressão, não inclua o arquivo CSV de estatísticas repetitivas no ZIP. Caso contrário, o console vai emitir um erro. O mesmo vale se você quiser fazer upload apenas de estatísticas repetitivas. - Arquivos de imagem do ícone: PNG (.png) ou JPEG (.jpg, .jpeg).
- Todos os ícones mencionados nos CSVs precisam existir na raiz do arquivo ZIP.
- Todos os arquivos de imagem presentes no ZIP precisam ser referenciados por pelo menos uma estatística.
- Estrutura do diretório: todos os arquivos precisam estar na raiz do arquivo ZIP. Não é permitido usar subdiretórios.
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,Event Property Name,Aggregation Type,Stat Display Name,Stat Description,Filter Property,Filter Operator,Filter Value,Is Competitive,Min limit,Max limit,Icon File Name,Good value direction,Unit
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
| ID da estatística | Obrigatório | Máximo de 100 caracteres Precisa conter apenas letras, números e sublinhados. Precisa ser exclusivo em todas as estatísticas do jogo. |
| Nome do evento | Obrigatório | Máximo de 50 caracteres Precisa fazer referência ao nome do evento definido no formato PlayerGameEvent.csv. |
| Nome da propriedade do evento | Obrigatório | Máximo de 50 caracteres |
| Nome de exibição da estatística | Obrigatório | Máximo de 50 caracteres Nome de exibição padrão da estatística (localidade padrão). Precisa ser exclusivo entre as estatísticas. |
| Descrição da estatística | Obrigatório | Máximo de 500 caracteres Descrição padrão da estatística. |
| Tipo de agregação | Obrigatório | Máximo de 50 caracteres SUM, MAX, MIN, COUNT. |
| Propriedade de filtro | Opcional | Máximo de 50 caracteres Precisa ser um nome de propriedade definido em PlayerGameEvent.csv. |
| Operador de filtro | Opcional | =, !=, >, <, >=, <=Operadores de comparação de filtro. |
| Filtrar por valor | Opcional | Em comparação com a propriedade de filtro.
O valor do filtro precisa ser INT64, DOUBLE, BOOL, STRING.
|
| É competitivo | Obrigatório | true, false
|
| Limite mínimo | Obrigatório quando "É competitivo" é verdadeiro | Pontuação mínima permitida para estatísticas competitivas. |
| Limite máximo | Obrigatório quando "É competitivo" é verdadeiro | Pontuação máxima permitida para estatísticas competitivas. |
| Nome do arquivo do ícone | Obrigatório | Nome de arquivo da imagem do ícone incluído na raiz do arquivo ZIP. Não pode entrar em conflito com os nomes de arquivos de ícones usados em estatísticas repetitivas. |
| Direção de valor bom | Obrigatório | Especifica se valores mais altos INCREASING ou mais baixos DECREASING são melhores.
|
| Unidade | Opcional | Unidade de medida para valores numéricos ou de duração brutos. Por exemplo, KILOMETER, SECOND, PERCENTAGE, UNITLESS. |
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 | Direção de valor bom | unidade |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | matchCompleted | duração | MAX | Sobrevivência da maior correspondência | Indica o tempo de sobrevivência de um jogador em qualquer partida | isWinner | = | TRUE | TRUE | 0 | 50 | stat1.png | Diminuindo | segundos |
| 2 | matchCompleted | isWinner | COUNT | Partidas vencidas | Indica o número de partidas que um jogador venceu. | isWinner | = | TRUE | TRUE | 0 | 50 | stat3.png | Aumentando | |
| 3 | matchCompleted | mortes | SUM | Eliminações em partidas 1 contra 1 | Número de eliminações em partidas 1 contra 1 | matchType | = | "1-on-1" | FALSO | stat4.png | Aumentando | |||
| 4 | itemCollected | coinsAmount | SUM | Total de ouro coletado | Jogador coletando moedas durante uma partida | weaponType | = | "sword" | FALSO | stat2.png | 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,Event Property Name,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 para um jogador no perfil dele.
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
| ID da estatística | Obrigatório | Máximo de 100 caracteres Precisa conter apenas letras, números e sublinhados. Precisa ser exclusivo em todas as estatísticas do jogo. |
| Nome da propriedade do evento | Obrigatório | Máximo de 50 caracteres Precisa ser um nome de propriedade definido no PlayerGameEvent.csv. |
| Nome de exibição da estatística | Obrigatório | Precisa ser um nome exclusivo. |
| Descrição da estatística | Obrigatório | Máximo de 50 caracteres Descrição padrão da estatística. |
| Nome do arquivo do ícone | Obrigatório | Nome de arquivo da imagem do ícone incluído na raiz do arquivo ZIP. Não pode entrar em conflito com os nomes de arquivos de ícones usados em estatísticas repetitivas. |
| Direção de valor bom | Obrigatório | Especifica se valores mais altos INCREASING ou mais baixos DECREASING são melhores.
|
| Unidade | Opcional | Unidade de medida para valores numéricos ou de duração brutos. Por exemplo, KILOMETER, SECOND, PERCENTAGE, UNITLESS. |
Exemplo de tabela
| ID da estatística | Nome da propriedade do evento | Nome de exibição da estatística | Stat Description | Nome do arquivo de ícone | Direção positiva de valor |
|---|---|---|---|---|---|
| 5 | currentProgress | Nível | Os jogadores acumulam XP jogando partidas e subindo 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,Locale,Localized Stat Display Name,Localized Stat Description
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
| ID da estatística | Obrigatório | Máximo de 100 caracteres Precisa conter apenas letras, números e sublinhados. Precisa ser exclusivo em todas as estatísticas do jogo. |
| Nome de exibição da estatística | Obrigatório | Precisa ser um nome exclusivo. |
| Localidade | Obrigatório | O código da localidade, como en-US. Adicione traduções para seu jogo antes de especificar uma localidade. Não é possível especificar a localidade padrão. Os códigos de localidade podem ser encontrados na lista de idiomas compatíveis. |
| Nome de exibição da estatística localizado | Opcional | Máximo de 50 caracteres. Nome de exibição traduzido da estatística para a localidade em questão. |
| Descrição localizada da estatística | Opcional | Máximo de 500 caracteres. Descrição traduzida da estatística para a localidade especificada. |
Exemplo de tabela
| ID da estatística | Nome de exibição da estatística | Código do idioma | Nome da estatística localizado (UTF-8) | Descrição localizada da estatística (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 | Or total collecté | Le joueur collecte des pièces en jouant un match |
Arquivos de ícones
Os ícones mencionados no arquivo CSV precisam existir no arquivo ZIP atual que você importa.
As regras de validação de ícones são:
| Propriedade de validação | Restrição / regra aplicada |
|---|---|
| Tamanho máximo do arquivo | Máximo de 1 MB (1.048.576 bytes) por arquivo de ícone. |
| Dimensões | Exatamente 512 × 512 pixels (largura = 512, altura = 512) |
| Proporção | Estritamente 1:1 (proporção quadrada) |
| Formatos permitidos | PNG (.png) e JPEG (.jpg, .jpeg) |
| Posição no CEP | Precisa estar localizado no diretório raiz do arquivo ZIP. |
| Verificação referenciada | Todos os nomes de arquivos de ícones especificados nas colunas "Nome do arquivo de ícone" precisam existir no ZIP. |
| Verificação de órfãos | Todos os arquivos de imagem no ZIP precisam ser referenciados por pelo menos uma estatística. |
| Verificação de conflitos | Os nomes de arquivos de ícones em ProgressionStatConfig.csv não podem
entrar em conflito com RepetitiveStatsConfig.csv.
|
| Cópias visuais | Os ícones duplicados são sinalizados. |
Diretrizes relativas a ícones
Os ícones precisam ser criados como arquivos PNG, JPEG ou JPG de 512 x 512 com planos de fundo transparentes.
O mesmo ícone é usado em todas as localidades. Portanto, recomendamos não incluir texto ou conteúdo localizado em um ícone.
Especificação da unidade
As colunas de unidade controlam como os valores de estatísticas brutos são formatados e localizados para os jogadores.
Propriedades de estatísticas numéricas (INT64, DOUBLE)
| Valor unitário permitido | Exemplo de valor bruto |
| (Empty) / UNITLESS / NONE | 1234567 |
| % / PERCENTAGE / PERCENT | 0,857 |
| Distância/comprimento: CENTIMETER, METER, KILOMETER, FOOT, INCH, MILE, YARD, MILLIMETER, NANOMETER | 15 (QUILÔMETRO) |
| Velocidade: KILOMETER_PER_HOUR, METER_PER_SECOND, MILE_PER_HOUR | 60 (MILE_PER_HOUR) |
Propriedades de estatísticas de duração (DURATION)
| Valor da categoria de formato | Valores de unidade permitidos | Exemplo de valor bruto | Exemplo de saída formatada |
| UNIT_BASED / DURATION | Obrigatório: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR | 5.400 segundos (HORA) | 1,5 hora |
| COMPONENT_NUMERIC / HH:MM:SS / CLOCK | Granularidade (opcional, padrão WHOLE_SECONDS): WHOLE_MINUTES, WHOLE_SECONDS, MILLISECONDS_ONE_DIGIT, MILLISECONDS_TWO_DIGITS, MILLISECONDS_THREE_DIGITS | 3.661 segundos | 01:01:01 |
| COMPONENT_TEXT / TEXT | Unidade menor (opcional, padrão SECONDS): SECONDS, MINUTES, HOURS, DAYS, MONTHS, YEARS | 90.000 segundos | 1d 1h |
Propriedades de estatísticas não numéricas (STRING, BOOL)
As colunas de unidade precisam ficar vazias.