Se usó la API de Cloud Translation para traducir esta página.

Cómo integrar la API de Recall de PGS en tu juego

En esta página, se explica cómo implementar la API de Recall en tu juego. En primer lugar, se describe cómo configurar el servidor y el cliente de juegos para admitir la API y, luego, se explica cómo almacenar y recuperar tokens.

Configuración del servidor de juegos

Configura tu servidor de juegos para que realice llamadas de la API de Recall a los servidores de Google.

1. Configura tu proyecto de los Servicios de juego de Play

Sigue las instrucciones que se indican en Cómo configurar los Servicios de juego de Google Play (si aún no lo hiciste).

2. Configura una cuenta de servicio para el juego

Sigue las instrucciones para crear una cuenta de servicio. Cuando las hayas completado, deberías tener un archivo JSON con las credenciales de la cuenta de servicio.

3. Descarga la biblioteca de Java del servidor para PlayGamesServices

Descarga la biblioteca google-api-services-games más reciente y súbela a tu servidor.

4. Prepara credenciales para las llamadas a la API de Recall

Consulta Preparación para realizar una llamada a la API autorizada para obtener más contexto.

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

Configuración del cliente de juegos

Configura tu cliente de juegos para que recupere los IDs de sesión de recuperación que usa tu servidor para comunicarse con los servidores de Google.

SDK de Java

Configura el SDK de Java en tu cliente y asegúrate de incluir com.google.android.gms:play-services-games-v2:19.0.0 y com.google.android.gms:play-services-tasks:18.0.2, o versiones posteriores, en tu archivo de Gradle.

Para comunicarte con los servidores de Google con la información correcta, debes solicitar un ID de sesión de recuperación desde el SDK cliente, que envías al servidor de tu juego.

Kotlin

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Java

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

SDK de Unity

Si aún no lo hiciste, configura el SDK de Unity en tu cliente.

Para comunicarte con los servidores de Google con la información correcta, debes solicitar un ID de sesión de recuperación desde el SDK cliente y enviarlo al servidor de tu juego.

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

Cómo usar la API de Recall en tu servidor de juegos

Después de configurar tu servidor y cliente, puedes enviar el recallSessionID desde tu cliente de juegos al servidor de juegos y seguir las instrucciones que se indican a continuación para comenzar a usar la API de Java y almacenar, recuperar o borrar de tokens de recuperación el servidor.

Cómo almacenar tokens

El arquetipo del usuario y el token de juego se pueden almacenar usando el objeto LinkPersonaRequest. Debes utilizar GoogleCredential para llamar a las APIs de Google (consulta Cómo llamar a las APIs de Google para obtener contexto). Ten en cuenta que, según la restricción de cardinalidad 1:1, solo puedes vincular un arquetipo a un perfil de los PGS a la vez (y viceversa). Debes establecer la política de resolución en caso de que este perfil de los PGS ya se haya vinculado con otro arquetipo.

De manera opcional, puedes establecer un TTL en el token, que declara durante cuánto tiempo es válido el token con un objeto Durations. Puedes elegir configurar esto con SetTtl() (como se muestra a continuación), que establece la fecha de vencimiento a partir de la cantidad de tiempo especificada en el método, o setExpireTime(), que te permite establecer el momento exacto del vencimiento de los tokens.

Debes encriptar el arquetipo y el token del juego, y estos no pueden contener información de identificación personal. Las cadenas de arquetipos y de tokens pueden tener un máximo de 256 caracteres, y puede haber un máximo de 20 tokens o arquetipos almacenados por jugador y por juego.

Solo se puede almacenar un token por arquetipo y por jugador en un momento determinado. Si intentas almacenar otro token con el mismo arquetipo, se reemplazará el token original.

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

Cómo recuperar tokens

Existen tres opciones para recuperar un token, según las necesidades de tus juegos. Puedes solicitar lo siguiente:

Son los tokens asociados con el juego actual, incluidos los tokens de recuperación específicos del juego.
Es el último token almacenado en todos los juegos que pertenecen a la cuenta de desarrollador.
Es una lista de los juegos que posee la cuenta de desarrollador y todos los tokens de recuperación asociados con cada juego.

Tokens de recuperación con alcance del juego

Para recuperar los tokens de recuperación del juego actual, obtén el recallSessionId del cliente y pásalo a la API de retrieveTokens:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

Es el token de recuperación más reciente en todos los juegos que pertenecen a la cuenta de desarrollador.

Para recuperar el token más reciente almacenado en todos los juegos que posee la cuenta de desarrollador en Google Play Console, debes obtener el recallSessionId del cliente y pasarlo a la API de lastTokenFromAllDeveloperGames, como se muestra en el siguiente fragmento de código. Como parte de la respuesta, puedes inspeccionar el ID de la aplicación asociado con este token.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

Todos los tokens de recuperación en una lista determinada de juegos propiedad de la cuenta de desarrollador

Para recuperar todos los tokens asociados con una lista de juegos que pertenecen a tu cuenta de desarrollador en Google Play Console, obtén el recallSessionId del cliente y pásalo a la API de gamesPlayerTokens. Proporciona una lista de IDs de aplicación.

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

Cómo borrar el token de recuperación

Si es necesario, también puedes borrar el token de recuperación con la siguiente llamada:

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

Cómo habilitar el modo sin perfil

Para habilitar la funcionalidad limitada de la API de Recall para los usuarios que no tienen perfiles de PGS, sigue estos pasos:

Habilita la recuperación sin perfil para tu proyecto de juego de PGS en Play Developer Console.
Revisa las condiciones adicionales que se describen más adelante en esta sección.
Agrega la siguiente etiqueta de metadatos a tu manifiesto de la app:

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

Condiciones adicionales

Además de estar sujeto a las Condiciones del Servicio de Play Juegos, aceptas que, si usas la API de Recall para usuarios sin un perfil de PGS, lo que permite compartir los datos del usuario final con Google sin que este tenga un perfil de Play Juegos, debes, antes de compartir esos datos con Google, proporcionar al usuario final un aviso adecuado que describa lo siguiente:

Compartir tus datos con Google para habilitar la función de vinculación de cuentas de Play Juegos
La disponibilidad de la configuración para administrar dicho uso compartido, como la configuración de Play Juegos
El tratamiento de dichos datos en virtud de la Política de Privacidad de Google, y obtener el consentimiento adecuado del usuario final para dicho intercambio que cumpla con todos los requisitos legales aplicables