PGS Recall API in dein Spiel integrieren

Auf dieser Seite wird erläutert, wie du die Recall API in deinem Spiel implementierst. Zuerst erfahren Sie, wie Sie den Spieleserver und den Client einrichten, um die API zu unterstützen. Anschließend erfahren Sie, wie Tokens gespeichert und abgerufen werden.

Gameserver einrichten

Richte deinen Gameserver so ein, dass Recall API-Aufrufe an Google-Server gesendet werden.

Play-Spieldienste-Projekt einrichten

Falls noch nicht geschehen: Folgen Sie der Anleitung unter Google Play-Spieldienste einrichten.

Hinweis :Recall-Tokens und -Identitäten sind pro PGS-Projekt verfügbar. Tokens und Personas werden also pro PGS-Projekt gespeichert. Für separate Play-Spieldienste-Projekte gibt es separate Sammlungen von Verknüpfungen zwischen Play-Spieldienste-Profilen und Identitäten. Wir empfehlen dir, diese Dokumentation zu lesen, wenn du ermittelst, wie du deine Play-Spieldienste-Projekte einrichtest.

Dienstkonto für das Spiel einrichten

Folgen Sie der Anleitung zum Erstellen eines Dienstkontos. Am Ende sollten Sie eine JSON-Datei mit Dienstkonto-Anmeldedaten haben.

Hinweis: Die Recall API ist eine reine Server-zu-Server-API. Aus diesem Grund verwendet die Recall API Dienstkonten zur Authentifizierung des Spieleservers und nicht reguläres dreibeiniges OAuth, das von der anderen Games API zur Authentifizierung sowohl von Spieleservern als auch von Endnutzern verwendet wird.

Serverseitige Java-Mediathek für Play-Spieldienste herunterladen

Laden Sie die neueste google-api-services-games-Bibliothek herunter und laden Sie sie auf Ihren Server hoch.

Anmeldedaten für Recall API-Aufrufe vorbereiten

Weitere Informationen finden Sie unter Delegierten API-Aufruf vorbereiten.

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();

Spielclient einrichten

Richte deinen Spieleclient so ein, dass er die Recall-Sitzungs-IDs abruft, die von deinem Server für die Kommunikation mit Google-Servern verwendet werden.

Java SDK

Richte das Java SDK in deinem Client ein und füge deiner Gradle-Datei com.google.android.gms:play-services-games-v2:19.0.0 und com.google.android.gms:play-services-tasks:18.0.2 oder höher hinzu.

Fordern Sie eine Recall-Sitzungs-ID vom Client SDK an, die Sie an den Server Ihres Spiels senden, um mit den Servern von Google mit den richtigen Informationen zu kommunizieren:

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
  });

Recall API auf deinem Spieleserver verwenden

Nachdem du den Server und den Client konfiguriert hast, kannst du das recallSessionID von deinem Spieleclient an deinen Spieleserver senden und der Anleitung unten folgen, um mit der Java API zum serverseitigen Speichern, Abrufen oder Löschen der Recall-Tokens zu beginnen.

Store-Tokens

Speichern Sie die Persona und das Spiel-Token des Nutzers mithilfe des LinkPersonaRequest-Objekts. Verwenden Sie GoogleCredential, um Google APIs aufzurufen. Um die 1:1-Kardinalitätsbeschränkung einzuhalten, kannst du jeweils nur eine Persona mit einem Play-Spieldienste-Profil verknüpfen und umgekehrt. Lege die Richtlinie für den Fall fest, dass dieses Play-Spieldienste-Profil bereits mit einer anderen Persona verknüpft wurde.

Optional können Sie eine TTL für das Token festlegen. Damit wird mithilfe eines Durations-Objekts angegeben, wie lange das Token gültig ist. Sie können dies mit SetTtl() festlegen (siehe unten), wodurch das Ablaufdatum auf den in der Methode angegebenen Zeitraum festgelegt wird. Mit setExpireTime() können Sie eine genaue Zeit festlegen, zu der die Tokens ablaufen.

Sie müssen die Persona und das Spiel-Token verschlüsseln. Diese dürfen keine personenidentifizierbaren Informationen enthalten. Persona- und Token-Strings dürfen maximal 256 Zeichen lang sein und es können maximal 20 Tokens oder Personas pro Spieler und Spiel gespeichert werden.

Pro Persona und Spieler kann jeweils nur ein Token gespeichert werden. Wenn Sie versuchen, ein anderes Token mit derselben Persona zu speichern, überschreibt das System das ursprüngliche Token.

Hinweis: Der Verschlüsselungsschlüssel, der zum Verschlüsseln von Tokens verwendet wird, sollte für jede Anwendung eindeutig sein. Wenn das Spiel an einen anderen Entwickler übertragen wird, muss der Verschlüsselungsschlüssel an den neuen Inhaber übergeben werden. Die Recall-Tokens können nicht ohne den ursprünglichen Verschlüsselungsschlüssel entschlüsselt werden.

import com.google.api.services.games.Games.Recall.LinkPersona;
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
}

Tokens abrufen

Zum Abrufen des Recall-Tokens rufen Sie das recallSessionId vom Client ab und übergeben es an die retrieveTokens API:

import com.google.api.services.games.Games.Recall.RetrieveTokens;

// ...

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
}

Hinweis :Strings, die die Persona darstellen, werden beim Anfordern von Recall-Tokens nicht über die API zurückgegeben.

Recall-Token löschen

Bei Bedarf können Sie das Recall-Token auch mit dem folgenden Aufruf löschen:

import com.google.api.services.games.Games.Recall.UnlinkPersona;

// ...

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();

// Confirm that the unlinking process completed successfully.
boolean unlinked = unlinkPersonaResponse.isUnlinked();