PGS Recall API in dein Spiel integrieren

Auf dieser Seite wird erläutert, wie du die Recall API in deinem Spiel implementierst. Zuerst wird beschrieben, wie Sie Ihren Spieleserver und Client für die API-Unterstützung einrichten. 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.

1. Play-Spieldienste-Projekt einrichten

Falls Sie dies noch nicht getan haben, folgen Sie der Anleitung unter Google Play-Spieldienste einrichten.

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

2. Dienstkonto für das Spiel einrichten

Folgen Sie der Anleitung zum Erstellen eines Dienstkontos. Am Ende sollten Sie eine JSON-Datei mit Anmeldedaten für das Dienstkonto 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 kein reguläres dreibeiniges OAuth, das von anderen Games API zur Authentifizierung sowohl von Spieleservern als auch von Endnutzern verwendet wird.

3. Serverseitige Java-Bibliothek für PlayGamesServices herunterladen

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

4. Anmeldedaten für Recall API-Aufrufe vorbereiten

Weitere Informationen finden Sie unter Vorbereitung eines autorisierten API-Aufrufs.

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

Einrichtung des Spieleclients

Richten Sie Ihren Spieleclient so ein, dass die Recall-Sitzungs-IDs abgerufen werden, die von Ihrem Server für die Kommunikation mit Google-Servern verwendet werden.

Java-SDK

Richten Sie das Java SDK in Ihrem Client ein und fügen Sie 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 in Ihre Gradle-Datei ein.

Damit du mit den richtigen Informationen mit den Google-Servern kommunizieren kannst, musst du vom Client SDK eine Recall-Sitzungs-ID anfordern, die du an den Server deines Spiels sendest.

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

Unity SDK

Falls noch nicht geschehen, richten Sie das Unity SDK in Ihrem Client ein.

Damit Sie mit den richtigen Informationen mit den Google-Servern kommunizieren können, müssen Sie vom Client SDK eine Recall-Sitzungs-ID anfordern und an den Server Ihres Spiels senden.

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

Recall API auf dem Gameserver verwenden

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

Store-Tokens

Die Persona und das Spieltoken der Nutzer können mithilfe des Objekts LinkPersonaRequest gespeichert werden. Sie müssen GoogleCredential verwenden, um Google APIs aufzurufen. Weitere Informationen finden Sie unter Google APIs aufrufen. Gemäß der 1:1-Kardinalitätseinschränkung kannst du jeweils nur eine Persona mit einem Play-Spieldienste-Profil verknüpfen und umgekehrt. Du solltest die Richtlinie für die Problemlösung festlegen, falls dieses Profil bereits mit einer anderen Persona verknüpft wurde.

Sie haben auch die Möglichkeit, eine TTL für das Token festzulegen. In dieser wird mit einem Durations-Objekt angegeben, wie lange das Token gültig ist. Sie können dies mit SetTtl() (wie unten gezeigt) festlegen, wodurch das Ablaufdatum in der in der Methode angegebenen Zeit festgelegt wird, oder mit setExpireTime(), um eine genaue Zeit für den Ablauf der Tokens festzulegen.

Sie müssen die Persona und das Spieltoken verschlüsseln und dürfen keine personenidentifizierbaren Informationen enthalten. Persona- und Tokenstrings dürfen höchstens 256 Zeichen lang sein. Pro Spieler und Spiel können maximal 20 Tokens oder Personas gespeichert werden.

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

Hinweis: Der zum Verschlüsseln von Tokens verwendete Verschlüsselungsschlüssel 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 ohne den ursprünglichen Verschlüsselungsschlüssel nicht entschlüsselt werden.

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
}

Token abrufen

Je nach den Anforderungen Ihres Spiels gibt es drei Möglichkeiten, ein Token abzurufen. Sie können Folgendes anfordern:

• Die mit dem aktuellen Spiel verknüpften Tokens, einschließlich Recall-Tokens auf Spielebene.
• Das letzte für alle Spiele des Entwicklerkontos gespeicherte Token.
• Bei einer Liste von Spielen, die dem Entwicklerkonto gehören, alle mit jedem Spiel verknüpften Recall-Tokens.

Hinweis :Wenn Sie Rückruftokens anfordern, gibt die API keine Strings zurück, die die Persona darstellen.

Recall-Tokens auf Spielebene

Wenn du die Recall-Tokens aus dem aktuellen Spiel abrufen möchtest, rufe die recallSessionId vom Client ab und übergib sie an die retrieveTokens API:

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
}

Aktuelles Recall-Token für alle Spiele des Entwicklerkontos

Wenn du das letzte Token abrufen möchtest, das für alle Spiele gespeichert ist, die dem Entwicklerkonto in der Google Play Console gehören, musst du das recallSessionId vom Client abrufen und an die lastTokenFromAllDeveloperGames API übergeben, wie im folgenden Code-Snippet gezeigt. Als Teil der Antwort können Sie die mit diesem Token verknüpfte Anwendungs-ID überprüfen.

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.
}

Alle Recall-Tokens für eine bestimmte Liste von Spielen, die dem Entwicklerkonto gehören

Wenn du alle Tokens abrufen möchtest, die mit einer Liste von Spielen verknüpft sind, die deinem Entwicklerkonto in der Google Play Console gehören, musst du die recallSessionId vom Client abrufen und an die gamesPlayerTokens API übergeben. Geben Sie eine Liste mit Anwendungs-IDs an.

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.
}

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

Profillosen Modus aktivieren

So kannst du eingeschränkte Recall API-Funktionen für Nutzer ohne Play-Spieldienste-Profile aktivieren:

1. Aktiviere in der Play Console den profillosen Recall für dein PGS-Spielprojekt.
2. Lesen Sie die zusätzlichen Bedingungen, die weiter unten in diesem Abschnitt beschrieben werden.
3. Füge deinem App-Manifest das folgende Metadaten-Tag hinzu:

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

Zusätzliche Bedingungen

Sie unterliegen nicht nur den Nutzungsbedingungen der Play-Spieldienste, sondern erklären sich auch damit einverstanden, dass Sie, wenn Sie die Recall API für Nutzer ohne Play-Spieldienste-Profil verwenden, die die Weitergabe von Endnutzerdaten an Google ermöglichen, ohne dass diese ein Play-Spieldienste-Profil haben, den Endnutzer vor der Weitergabe solcher Daten an Google entsprechend informieren müssen. 1) Ihre Freigabe der Daten für die entsprechenden Datenverarbeitungs- und Datenschutzanforderungen für Google Play Spiele und die entsprechenden Einstellungen zur Kontoverknüpfung von Play Spiele 2.