Conquistas em jogos para Android

Este guia descreve como usar as APIs de conquistas em um aplicativo Android para desbloquear e mostrar conquistas no seu jogo. As APIs podem ser encontradas nos pacotes com.google.android.gms.games e com.google.android.gms.games.achievements.

Antes de começar

Caso ainda não tenha feito isso, recomendamos consultar os conceitos de conquistas no jogo.

Antes de começar a programar usando a API de conquistas:

• Siga as instruções do guia Configurar o SDK do Google Play Services para instalar e configurar seu app para usar os serviços relacionados a jogos do Google Play.
• Defina as conquistas que você quer que o jogo desbloqueie ou mostre seguindo as instruções do guia do Google Play Console.
• Faça o download e analise os exemplos de código de conquistas na página de exemplos do Android (em inglês).
• Conheça melhor as recomendações descritas na Lista de verificação de qualidade.

Acessar um cliente de conquistas

Para começar a usar a API de conquistas, o jogo precisa ter um objeto AchievementsClient. Para fazer isso, chame o método Games.getAchievementClient() e transmita a atividade e o GoogleSignInAccount do player atual. Para saber como recuperar as informações da conta do jogador, consulte Fazer login em jogos Android.

Desbloquear conquistas

Para desbloquear uma conquista, chame o método AchievementsClient.unlock() e transmita o ID da conquista.

O snippet de código abaixo mostra como o app pode desbloquear conquistas:

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .unlock(getString(R.string.my_achievement_id));

Se a conquista for do tipo incremental (ou seja, várias etapas são necessárias para o desbloqueio), chame AchievementsClient.increment().

O snippet de código abaixo mostra como o app pode incrementar a conquista do jogador:

Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
    .increment(getString(R.string.my_achievement_id), 1);

Não é necessário escrever outros códigos para desbloquear a conquista. Os serviços relacionados a jogos do Google Play desbloqueiam a conquista automaticamente quando ela atinge o número necessário de etapas.

É recomendado definir os IDs de conquista no arquivo strings.xml para que o jogo possa referenciar as conquistas por ID de recurso. Ao fazer chamadas para atualizar e carregar conquistas, siga as práticas recomendadas para evitar exceder a cota de APIs.

Mostrar conquistas

Para mostrar as conquistas de um jogador, chame AchievementsClient.getAchievementsIntent() para receber uma Intent e criar a interface padrão de conquistas do usuário. Em seguida, o jogo pode mostrar a IU chamando startActivityForResult.

O snippet de código abaixo mostra como o app pode exibir a interface padrão de conquistas do usuário. No snippet, RC_ACHIEVEMENT_UI é um número inteiro arbitrário que o jogo usa como código de solicitação.

private static final int RC_ACHIEVEMENT_UI = 9003;

private void showAchievements() {
  Games.getAchievementsClient(this, GoogleSignIn.getLastSignedInAccount(this))
      .getAchievementsIntent()
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_ACHIEVEMENT_UI);
        }
      });
}

Confira abaixo um exemplo da IU de conquistas padrão.