Acceso a juegos para Android

Para acceder a la funcionalidad de los Servicios de juego de Google Play, tu juego debe proporcionar la cuenta del jugador que accedió. Si el jugador no está autenticado, es posible que el juego genere errores cuando realice llamadas a las APIs de los Servicios de juego de Google Play. En esta documentación, se describe cómo implementar una experiencia perfecta de acceso en tu juego.

Implementa el acceso del jugador

La clase GoogleSignInClient es el punto de entrada principal para recuperar la cuenta del jugador que accedió en el momento y para que acceda si no lo hizo antes en tu app en el dispositivo.

Para crear un cliente de acceso, sigue estos pasos:

  1. Crea un cliente de acceso a través del objeto GoogleSignInOptions, como se muestra en el siguiente fragmento de código. En GoogleSignInOptions.Builder, para configurar el acceso, debes especificar GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN.

    GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  2. Si deseas usar un SnapshotsClient, agrega .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) a tu GoogleSignInOptions.Builder, como se muestra en el siguiente fragmento de código:

    GoogleSignInOptions  signInOptions =
        new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
            .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
            .build();
  3. Llama al método GoogleSignIn.getClient() y pasa las opciones que configuraste en los pasos anteriores. Si la llamada se realiza correctamente, la API de Google Sign-In muestra una instancia de GoogleSignInClient.

Verifica si el jugador ya accedió

Puedes verificar si una cuenta ya accedió en el dispositivo actual con GoogleSignIn.getLastSignedInAccount() y si esta cuenta ya tiene otorgados los permisos necesarios con GoogleSignIn.hasPermissions(). Si se cumplen ambas condiciones (es decir, getLastSignedInAccount() muestra un valor no nulo y hasPermissions() muestra true), puedes usar de forma segura la cuenta que muestra getLastSignedInAccount(), incluso si el dispositivo está sin conexión.

Realizar un acceso silencioso

Puedes llamar a silentSignIn() para recuperar la cuenta del jugador que accedió y tratar de que los jugadores accedan sin mostrar una interfaz de usuario si accedieron correctamente a tu app en otro dispositivo.

El método silentSignIn() muestra un Task<GoogleSignInAccount>. Cuando se complete la tarea, debes configurar el campo GoogleSignInAccount que declaraste antes en la cuenta de acceso que la tarea muestra como resultado, o en null, lo que indica que no hay un usuario que haya accedido.

Si falla el intento de acceso silencioso, puedes enviar de manera opcional el intent de acceso para que muestre una interfaz de usuario de acceso, como se describe en Cómo realizar un acceso interactivo.

Como el estado del jugador que accedió puede cambiar cuando la actividad no está en primer plano, te recomendamos que llames a silentSignIn() desde el método onResume() de la actividad.

Para acceder de forma silenciosa, sigue estos pasos:

  1. Llama al método silentSignIn() en GoogleSignInClient para iniciar el flujo de acceso silencioso. Esta llamada muestra un objeto Task<GoogleSignInAccount> que contiene un GoogleSignInAccount si el acceso silencioso se realiza correctamente.
  2. Anula OnCompleteListener para controlar el éxito o el fracaso del acceso del jugador.
    • Si la tarea de acceso se realizó correctamente, llama a getResult() para obtener el objeto GoogleSignInAccount.
    • Si el acceso no se realizó correctamente, puedes enviar un intent de acceso para iniciar un flujo de acceso interactivo. Para obtener una lista de los objetos de escucha de devolución de llamada adicionales que puedes usar, consulta la Guía para desarrolladores de la API de Tasks y la referencia de la API de Task.

En el siguiente fragmento de código, se muestra cómo tu app puede realizar el acceso silencioso:

private void signInSilently() {
  GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
  if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) {
    // Already signed in.
    // The signed in account is stored in the 'account' variable.
    GoogleSignInAccount signedInAccount = account;
  } else {
    // Haven't been signed-in before. Try the silent sign-in first.
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            new OnCompleteListener<GoogleSignInAccount>() {
              @Override
              public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
                if (task.isSuccessful()) {
                  // The signed in account is stored in the task's result.
                  GoogleSignInAccount signedInAccount = task.getResult();
                } else {
                  // Player will need to sign-in explicitly using via UI.
                  // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in,
                  // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement
                  // Interactive Sign-in.
                }
              }
            });
  }
}

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

Si falla el intento de acceso silencioso, puedes llamar a getException() para obtener un ApiException con el código de estado detallado. Un código de estado de CommonStatusCodes.SIGN_IN_REQUIRED indica que el jugador debe realizar una acción explícita para acceder. En este caso, tu app debe iniciar un flujo de acceso interactivo, como se describe en la siguiente sección.

Cómo realizar un acceso interactivo

Para acceder con la interacción del jugador, la app debe iniciar el intent de acceso. Si se realiza correctamente, la API de Acceso con Google muestra una interfaz de usuario que le solicita al jugador que ingrese sus credenciales para acceder. Este enfoque simplifica el desarrollo de tu app, ya que la actividad de acceso maneja situaciones como la necesidad de actualizar los Servicios de Google Play o mostrar solicitudes de consentimiento en nombre de tu app. El resultado se muestra a través de la devolución de llamada onActivityResult.

Para acceder de forma interactiva, sigue estos pasos:

  1. Llama a getSigninIntent() en el GoogleSignInClient para obtener un intent de acceso y, luego, llama a startActivity() y pasa ese intent. En el siguiente fragmento de código, se muestra cómo tu app puede iniciar un flujo de acceso interactivo:

    private void startSignInIntent() {
      GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
          GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
      Intent intent = signInClient.getSignInIntent();
      startActivityForResult(intent, RC_SIGN_IN);
    }
  2. En la devolución de llamada onActivityResult(), controla el resultado del intent que se muestra.

    • Si el resultado del acceso fue exitoso, obtén el objeto GoogleSignInAccount de GoogleSignInResult.
    • Si el resultado de acceso no se realizó correctamente, debes controlar el error de acceso (por ejemplo, mostrando un mensaje de error en una alerta). En el siguiente fragmento de código, se muestra cómo la app puede controlar los resultados del acceso del jugador:
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
      super.onActivityResult(requestCode, resultCode, data);
      if (requestCode == RC_SIGN_IN) {
        GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
        if (result.isSuccess()) {
          // The signed in account is stored in the result.
          GoogleSignInAccount signedInAccount = result.getSignInAccount();
        } else {
          String message = result.getStatus().getStatusMessage();
          if (message == null || message.isEmpty()) {
            message = getString(R.string.signin_other_error);
          }
          new AlertDialog.Builder(this).setMessage(message)
              .setNeutralButton(android.R.string.ok, null).show();
        }
      }
    }

Cómo recuperar información del jugador

El GoogleSignInAccount que muestra la API de Acceso con Google no contiene información del jugador. Si tu juego usa información del jugador, como su nombre visible y su ID, puedes seguir estos pasos para recuperarla.

  1. Para obtener un objeto PlayersClient, llama al método getPlayersClient() y pasa GoogleSignInAccount como parámetro.
  2. Usa los métodos PlayersClient para cargar de forma asíncrona el objeto Player que contiene la información de un jugador. Por ejemplo, puedes llamar a getCurrentPlayer() para cargar el jugador que accedió. Si la tarea muestra un ApiException con el código de estado SIGN_IN_REQUIRED, significa que se debe volver a autenticar el reproductor. Para ello, llama a GoogleSignInClient.getSignInIntent() para que el jugador acceda de forma interactiva.
  3. Si la tarea muestra correctamente el objeto Player, puedes llamar a los métodos del objeto Player para recuperar detalles específicos del jugador (por ejemplo, getDisplayName() o getPlayerId()).

Proporciona un botón de acceso

Para proporcionar un botón de acceso de Google estándar en tu juego, puedes usar uno de estos enfoques:

Cuando los usuarios hacen clic en el botón de acceso, el juego debe iniciar el flujo de acceso enviando un intent de acceso, como se describe en Cómo realizar un acceso interactivo.

En este fragmento de código, se muestra cómo puedes agregar un botón de acceso en el método onCreate() para tu actividad.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_sign_in);
  findViewById(R.id.sign_in_button).setOnClickListener(this);
  findViewById(R.id.sign_out_button).setOnClickListener(this);
}

En el siguiente fragmento de código, se muestra cómo puedes enviar el intent de acceso cuando el usuario hace clic en el botón de acceso.

@Override
public void onClick(View view) {
  if (view.getId() == R.id.sign_in_button) {
    // start the asynchronous sign in flow
    startSignInIntent();
  } else if (view.getId() == R.id.sign_out_button) {
    // sign out.
    signOut();
    // show sign-in button, hide the sign-out button
    findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE);
    findViewById(R.id.sign_out_button).setVisibility(View.GONE);
  }
}

Muestra ventanas emergentes del juego

Puedes mostrar vistas emergentes en tu juego con la clase GamesClient. Por ejemplo, el juego puede mostrar una ventana emergente de "Te damos la bienvenida" o "Logros desbloqueados". Para permitir que los Servicios de juego de Google Play lancen ventanas emergentes en las vistas de tu juego, llama al método setViewForPopups(). Para personalizar aún más dónde aparece la ventana emergente en la pantalla, llama a setGravityForPopups().

Cómo cerrar la sesión del jugador

Para salir, llama al método signOut() en GoogleSignInClient.

private void signOut() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  signInClient.signOut().addOnCompleteListener(this,
      new OnCompleteListener<Void>() {
        @Override
        public void onComplete(@NonNull Task<Void> task) {
          // at this point, the user is signed out.
        }
      });
}