Este documento explica como integrar conquistas ao seu jogo usando o Google Play Console ou chamadas de API. Ele aborda os elementos e estados essenciais das conquistas e descreve como criar, importar e gerenciar essas conquistas.
Antes de começar
Leia as diretrizes para criar conquistas de alta qualidade.
Consulte a terminologia em princípios básicos das conquistas.
Criar ou importar novas conquistas
Para implementar conquistas do zero, siga estas etapas:
Adicionar conquistas
Há duas maneiras de criar conquistas usando o Google Play Console:
- Criar uma conquista: adicione definições e metadados para cada conquista.
- Importar conquistas: importe definições e outros metadados de várias conquistas em uma única etapa.
Criar uma conquista
Para criar uma conquista para um jogo novo e não publicado, siga estas etapas:
- No Google Play Console, selecione um jogo.
- Na página Serviços relacionados a jogos do Google Play: conquistas (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas), selecione Criar conquista.
- Na página Adicionar conquistas, preencha o formulário.
- Clique em Salvar como rascunho.
- Depois de criar uma conquista, você precisa publicar as conquistas.
Importar conquistas
Para adicionar várias conquistas ao jogo de uma só vez, siga estas etapas:
- Crie um arquivo ZIP com suas conquistas.
- Enviar o arquivo.
Para mais informações, consulte as diretrizes para arquivos ZIP.
Para importar conquistas:
- No Google Play Console, selecione um jogo.
- Na página Serviços relacionados a jogos do Google Play - Conquistas (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas), selecione Importar conquistas.
- Na página Importar conquistas, clique em Fazer upload.
- Selecione o arquivo ZIP.
- Clique em Salvar como rascunho.
- Depois de importar as conquistas, publique o jogo.
Diretrizes para arquivos ZIP
É possível importar várias conquistas 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 |
|---|---|---|
AchievementsMetadata.csv
|
Obrigatório | Metadados de cada conquista. Consulte Atributos. |
AchievementsLocalizations.csv
|
Opcional | Fornece traduções para nomes e descrições de conquistas. |
AchievementsIconMappings.csv
|
Opcional | Faz a correspondência entre conquistas e os arquivos de ícones. |
| Arquivos de ícones | Opcional | Ícones nos formatos PNG, JPEG ou JPG. |
Requisitos do arquivo ZIP:
- Sem subdiretórios.
- Nomes de arquivos exclusivos.
- Somente arquivos CSV, PNG, JPEG ou JPG.
- Os arquivos CSV não podem ter uma linha de cabeçalho.
- Cada arquivo precisa ter menos de 1 MB.
- O arquivo ZIP não pode ter mais de 203 arquivos.
- O tamanho total do arquivo ZIP precisa ser inferior a 200 MB.
Formato AchievementsMetadata.csv
O arquivo AchievementsMetadata.csv contém os metadados de cada conquista. Ele precisa incluir as informações como valores separados por vírgula na seguinte ordem:
Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Valores aceitos |
|---|---|---|
| Nome | Obrigatório | Máximo de 100 caracteres |
| Descrição | Opcional | Máximo de 500 caracteres |
| Valor incremental | Opcional | True ou False
|
| Etapas necessárias | Obrigatório se Incremental Value for True.
|
Número (sem frações ou decimais) |
| Estado inicial | Obrigatório | Hidden ou Revealed
|
| Pontos | Obrigatório | Número múltiplo de 5, com valor entre 5 e 200 |
| Ordem da lista | Opcional | Número (sem frações ou decimais e maior que zero) |
Requisitos do arquivo AchievementsMetadata.csv:
- Cada linha precisa ter sete valores. Se você quiser omitir um valor, deixe o campo em branco.
- Os campos
NameeDescriptionsão usados como a localidade padrão. - O campo
Nameprecisa ser exclusivo em todas as conquistas. - Os campos a seguir não podem conter vírgulas:
NameeDescription.
Exemplo de arquivo AchievementsMetadata.csv:
Achievement1,Achievement One,True,100,Hidden,5,20 Achievement2,Achievement Two,False,,Revealed,10,30
Formato AchievementsLocalizations.csv
O arquivo AchievementsLocalizations.csv é opcional e configura todos os dados necessários para descrever cada conquista aos usuários em diferentes localidades. As conquistas são traduzidas de acordo com as localidades
especificadas para o jogo.
Ele precisa incluir as informações como valores separados por vírgula na seguinte ordem:
Name, Localized name, Localized description, locale
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Descrição | Valores aceitos |
|---|---|---|---|
| Nome | Obrigatório | Precisa corresponder à coluna Name de AchievementsMetadata.csv.
|
Máximo de 100 caracteres |
| Nome localizado | Obrigatório | O nome localizado da conquista. | Máximo de 100 caracteres |
| Descrição localizada | Opcional | A descrição localizada da conquista na localidade especificada. | Máximo de 500 caracteres |
| 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 compatíveis podem ser encontrados na lista de idiomas compatíveis. |
Requisitos do arquivo AchievementsLocalizations.csv:
- Os nomes das conquistas em um jogo precisam ser exclusivos por localidade.
Por exemplo, se um jogo tiver suporte para as localidades en-US e fr-FR, uma conquista chamada "Conquista1" em en-US também pode ser chamada de "Conquista1" em fr-FR.
- Cada linha precisa ter quatro valores. Se você quiser omitir o valor da descrição localizada, deixe o campo em branco.
Exemplo de arquivo AchievementsLocalizations.csv:
Achievement1,Achievement One,This is the description of achievement one in English.,en-US Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR Achievement2,Achievement Two,Description of achievement two.,en-US Achievement2,Logro Dos,Descripción del logro dos.,es-ES Achievement3,Achievement Three,,en-US Achievement3,Erfolg Drei,,de-DE
Formato AchievementsIconMappings.csv
O arquivo AchievementsIconMappings.csv é opcional e é usado para fazer a correspondência entre suas conquistas e o ícone fornecido. Ele precisa incluir as informações como valores separados por vírgula na seguinte ordem:
Name, icon filename
Esses campos são descritos na tabela a seguir:
| Títulos de colunas do CSV | Obrigatório ou opcional | Descrição |
|---|---|---|
| Nome | Obrigatório | Precisa corresponder à coluna Name de AchievementsMetadata.csv.
|
| Nome do arquivo do ícone | Obrigatório | O nome do arquivo do ícone. |
Requisitos do arquivo AchievementsIconMappings.csv:
- Cada linha precisa ter dois valores.
- Os arquivos de ícones só podem estar nos formatos PNG ou JPEG.
Exemplo de arquivoAchievementsIconMappings.csv:
Valid Achievement,valid-achievement-icon.png Incremental Achievement,incremental-achievement-icon.jpeg No Description,no-description-icon.png Hidden Initial State,hidden-initial-state-icon.png Large Point Value,large-point-value-icon.jpeg
Diretrizes relativas a ícones
Os ícones precisam ser criados como arquivos PNG, JPEG ou JPG de 512 x 512. Você só precisa nos fornecer o ícone para a conquista desbloqueada. Vamos gerar automaticamente uma versão em escala de cinza para o ícone revelado. Por isso, recomendamos que os ícones de conquista incluam elementos coloridos para que os usuários possam distinguir entre conquistas reveladas e desbloqueadas.
Quando um ícone de conquista é exibido em um [aviso][a] do Android, ele aparece sobreposto por um círculo com os cantos externos ocultos. Confira se o ícone ainda é exibido de maneira adequada nessas circunstâncias.
O mesmo ícone é usado em todas as localidades. Portanto, recomendamos não incluir texto ou conteúdo localizado em um ícone.
Arquivos de ícones
Os ícones mencionados no arquivo AchievementsIconMappings.csv precisam existir no arquivo ZIP atual que você importa.
Atualizar jogos com conquistas atuais
É possível adicionar mais conquistas a um jogo e atualizar as existentes no Google Play Console.
Adicionar mais conquistas
Se você já tem conquistas e quer adicionar mais:
- No Google Play Console, selecione um jogo.
- Na página Serviços relacionados a jogos do Google Play: conquistas (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas), selecione Adicionar conquistas.
Editar conquistas
Se você já tem conquistas e quer editar:
- No Google Play Console, selecione um jogo.
- Na página Serviços relacionados a jogos do Google Play: conquistas (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas), selecione uma conquista.
- É possível editar qualquer um dos campos.
- Clique em Salvar como rascunho.
- Na página Serviços relacionados a jogos do Google Play - Conquistas, a conquista editada está com o status "Disponível para testadores".
- Depois de testar a conquista, clique em Revisar e publicar.
Assim, seu jogo será republicado com todas as conquistas atualizadas.
Excluir uma conquista
Após a publicação da conquista, ela não poderá ser excluída. Só é possível excluir uma conquista em um estado pré-publicado
- Na página Serviços relacionados a jogos do Google Play - Conquistas, selecione uma conquista.
- Para excluir a conquista, clique em Excluir conquista.
Redefinir uma conquista
Só é possível redefinir os dados de progresso do jogador para conquistas de rascunho.
- Na página Serviços relacionados a jogos do Google Play - Conquistas, selecione uma conquista.
- Para redefinir as conquistas, clique em Redefinir progresso.
- Para redefinir os dados de conquista de forma programática, chame os
métodos
Achievementsda API Management.
Adicionar traduções para conquistas
Você pode especificar suas próprias traduções para conquistas associadas ao seu jogo. Antes de fazer isso, conclua as etapas descritas em Como adicionar traduções ao seu jogo.
Há duas maneiras de fazer isso:
Use a opção Importar conquistas para fazer upload de traduções de muitas conquistas novas de uma vez. Não é possível usar essa opção para fazer upload de traduções de conquistas que já existem.
Adicionar traduções para cada conquista no seu jogo. Para adicionar sua própria tradução para cada conquista:
- No Google Play Console, abra a guia Conquistas do jogo e selecione uma delas.
- Na página de detalhes das conquistas, selecione a guia de um idioma adicionado anteriormente na guia Detalhes do jogo.
- Na página de detalhes desse idioma, edite o formulário com as traduções.
- Clique em Salvar para armazenar os detalhes traduzidos da conquista.
Implementações do cliente
Para saber como implementar conquistas na sua plataforma, consulte os seguintes recursos:
Como testar conquistas
Para verificar se as conquistas funcionam conforme o esperado, siga as etapas para testá-las:
- Configure uma faixa de teste interno.
- Adicione contas de teste ao projeto do jogo para os testadores.
- Crie um perfil dos serviços relacionados a jogos do Google Play para uma das contas de teste usando o app Google Play Games.
- Abra o jogo usando a mesma conta de teste para a qual você criou o perfil dos serviços relacionados a jogos do Google Play.
- Verifique se o "toast de boas-vindas" dos serviços relacionados a jogos do Google Play aparece na tela como uma confirmação da autenticação automática bem-sucedida no lançamento do jogo.
- Jogue e conclua as etapas necessárias para desbloquear as conquistas.
Para verificar as conquistas:
Verifique se o pop-up "Conquista desbloqueada" aparece na tela quando a conquista é concluída.
Abra o app Play Store e verifique se a seção de conquistas na guia "Você" mostra as conquistas concluídas e em andamento (com detalhes do progresso).
Acompanhar o desempenho das conquistas no Play Console
Veja como encontrar estatísticas rápidas de conquistas individuais:
- No Google Play Console.
- Acesse Configurações> Projetos de jogos.
- Selecione um jogo.
- No menu à esquerda, clique em Conquistas.
- Na página Conquistas, você encontra estatísticas para entender se os jogadores estão desbloqueando as conquistas. Para quem não tem as conquistas ocultas, é possível ver qual porcentagem está desbloqueando cada uma delas. Para conquistas de estágio inicial, a porcentagem de desbloqueio geralmente fica mais próxima de 100%.
Você também pode acompanhar a performance das conquistas em séries temporais na página Crescimento > Serviços relacionados a jogos do Google Play > Estatísticas do jogo.
Publicar as conquistas
Depois de terminar os testes, publique o jogo. Todas as conquistas do jogo são publicadas com ele. A publicação de conquistas é uma etapa obrigatória para que elas funcionem corretamente.
Para publicar, siga estas etapas:
- No Google Play Console, selecione um jogo.
- Na página Serviços relacionados a jogos do Google Play: conquistas (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas), clique em Analisar e publicar.
- Na página Publicação dos Serviços relacionados a jogos do Google Play (Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Publicação), analise as ações e corrija os problemas.
- Clique em Publicar.
Todas as conquistas do jogo são publicadas.
Erros comuns a serem evitados
Esses pontos destacam erros comuns que devem ser evitados ao implementar conquistas em um jogo. Eles enfatizam a importância de:
No Play Console, acesse Crescimento > Serviços relacionados a jogos do Google Play > Configuração e gerenciamento > Conquistas.
- Antes de publicar, verifique se as conquistas configuradas no Play Console não estão no estado "Rascunho".
- Não adicione valores de ID de conquistas do Play Console ao código do jogo. Use as implementações de cliente.
Verifique se você também implementou a lógica de desbloqueio no seu cliente.
- Os jogadores não podem pular a etapa de acionamento em que a API de desbloqueio é chamada. Por exemplo, concluir o tutorial é uma conquista, mas os jogadores podem pular o tutorial.