Placares em jogos para Android

Este guia mostra como usar as APIs de placares em um app Android para criar placares visuais, registrar a pontuação de um jogador e comparar a pontuação com a de sessões anteriores do jogo. As APIs podem ser encontradas nos pacotes com.google.android.gms.games e com.google.android.gms.games.leaderboards.

Antes de começar

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

Antes de começar a programar usando as APIs de placares:

• 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 os placares que você quer que o jogo mostre ou atualize seguindo as instruções no guia do Google Play Console.

• Faça o download e confira os exemplos de código dos placares na página de exemplos do Android (link em inglês) no GitHub.

• Conheça melhor as recomendações descritas na Lista de verificação de qualidade.

Acessar o cliente de placares

Para começar a usar a API de placares, o jogo precisa ter um objeto LeaderboardsClient. Para isso, chame o método Games.getLeadeboardsClient() e transmita a atividade.

Atualizar a pontuação dos jogadores

Quando a pontuação do jogador muda (por exemplo, quando ele termina uma partida), o jogo pode atualizar o placar chamando LeaderboardsClient.submitScore() e transmitindo o ID do placar e o valor bruto da pontuação.

O snippet de código abaixo mostra como o app pode atualizar a pontuação do jogador:

PlayGames.getLeaderboardsClient(this)
    .submitScore(getString(R.string.leaderboard_id), 1337);

É recomendado definir o ID do placar no arquivo strings.xml para que o jogo possa referenciar os placares pelos IDs de recurso. Ao fazer chamadas para atualizar e carregar pontuações de jogadores, siga as práticas recomendadas para evitar exceder sua cota de APIs.

Mostrar um placar

Para mostrar o placar, chame LeaderboardsClient.getLeaderboardIntent() para receber um Intent e criar a interface do usuário padrão. Em seguida, o jogo pode mostrar a IU chamando startActivityForResult.

O snippet de código abaixo mostra como o app pode atualizar a pontuação do jogador. No snippet de código, RC_LEADERBOARD_UI é um número inteiro arbitrário para o código da solicitação.

private static final int RC_LEADERBOARD_UI = 9004;

private void showLeaderboard() {
  PlayGames.getLeaderboardsClient(this)
      .getLeaderboardIntent(getString(R.string.leaderboard_id))
      .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent intent) {
          startActivityForResult(intent, RC_LEADERBOARD_UI);
        }
      });
}

Mesmo que nenhum resultado seja retornado, você precisa usar startActivityForResult para que a API possa receber a identidade do pacote de chamada. Confira abaixo um exemplo da IU de placar padrão.