PGS Recall API in dein Spiel integrieren

Auf dieser Seite wird beschrieben, wie Sie die Recall API in Ihr Spiel implementieren. Zuerst wird beschrieben, wie Sie Ihren Gameserver und ‑client für die API einrichten. Anschließend wird erläutert, wie Sie Tokens speichern und abrufen.

Gameserver-Einrichtung

Richten Sie Ihren Gameserver so ein, dass er Recall API-Aufrufe an Google-Server sendet.

1. Play-Spieldienste-Projekt einrichten

Falls noch nicht geschehen, folgen Sie der Anleitung unter Google Play-Spieldienste einrichten.

Hinweis :Rückruftokens und Identitäten sind pro PGS-Projekt verfügbar. Das bedeutet, dass Tokens und Identitäten pro PGS-Projekt gespeichert werden. Für separate PGS-Projekte gibt es separate Sammlungen von Verknüpfungen zwischen PGS-Profilen und Identitäten. Wir empfehlen, diese Dokumentation zu lesen, um zu erfahren, wie Sie Ihre PGS-Projekte einrichten.

2. Dienstkonto für das Spiel einrichten

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

Hinweis :Die Recall API ist eine Server-zu-Server-API. Aus diesem Grund verwendet die Recall API Dienstkonten zur Authentifizierung des Spielservers und nicht das reguläre 3-Legged-OAuth, das von anderen Spiele-APIs zur Authentifizierung von Spielservern und Endnutzern verwendet wird.

3. Serverseitige Java-Bibliothek für Play Games Services 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 Autorisierten 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();

Einrichtung des Spieleclients

Richte deinen Spieleclient so ein, dass er die Recall-Sitzungs-IDs abruft, die von unserem 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 hinzu.

und com.google.android.gms:play-services-tasks:18.0.2 oder höher in Ihrer Gradle-Datei.

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

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

Richten Sie das Unity SDK in Ihrem Client ein, falls noch nicht geschehen.

Damit Sie mit den Servern von Google mit den richtigen Informationen kommunizieren können, müssen Sie eine Recall-Sitzungs-ID vom Client-SDK 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 Ihrem Gameserver verwenden

Nachdem Sie Ihren Server und Client konfiguriert haben, können Sie die recallSessionID von Ihrem Spieleclient an Ihren Gameserver senden und der folgenden Anleitung folgen, um die Java API zum serverseitigen Speichern, Abrufen oder Löschen der Recall-Tokens zu verwenden.

Tokens speichern

Ein Spielerkonto in der Google Play Games Recall API besteht aus zwei Informationen:

• Eine Identität, die als stabile Kennzeichnung für ein In-Game-Konto dient
• Ein Token, das als Schlüssel zum sicheren Anmelden eines Spielers im Konto dient

Sie können die Persona und das Token eines Nutzers mit dem LinkPersonaRequest-Objekt speichern. Verwenden Sie GoogleCredential, um Google-APIs aufzurufen (siehe Google-APIs aufrufen). Für eine Identität gilt eine 1:1-Kardinalitätseinschränkung: Ein einzelnes PGS-Profil kann nur eine einzelne Identität enthalten und eine Identität kann nur in einem einzelnen PGS-Profil vorhanden sein. Legen Sie die Richtlinie zur Auflösung von Konflikten bei Links fest, um zu definieren, wie Verstöße gegen die 1:1-Kardinalitätsbeschränkung behoben werden sollen.

Legen Sie optional die Ablaufzeit des Tokens fest. Verwende SetTtl() mit einem Durations-Objekt, um eine Time-to-Live festzulegen oder mit setExpireTime() eine genaue Ablaufzeit anzugeben.

Sie müssen das Persona- und das Spieltoken verschlüsseln. Sie dürfen keine personenidentifizierbaren Informationen enthalten. Persona- und Token-Strings dürfen maximal 256 Zeichen lang sein.

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 weitergegeben werden. Die Speicherdaten-Tokens können ohne den ursprünglichen Verschlüsselungsschlüssel nicht entschlüsselt werden.

Hinweis :Für Nutzer ohne Profil erstellte Tokens haben eine Standard-TTL von 30 Tagen. Andernfalls haben Tokens für Nutzer mit PGS-Profilen keine Standard-TTL.

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
}

Tokens abrufen

Je nach den Anforderungen Ihrer Spiele haben Sie drei Möglichkeiten, ein Token abzurufen. Sie können Folgendes anfordern:

• Die mit dem aktuellen Spiel verknüpften Tokens, einschließlich der spielbezogenen Recall-Tokens.
• Das letzte Token, das in allen Spielen gespeichert wurde, die dem Entwicklerkonto gehören.
• Eine Liste der Spiele, die dem Entwicklerkonto gehören, sowie alle Speicherdaten-Tokens, die mit den einzelnen Spielen verknüpft sind.

Hinweis :Wenn Sie Recall-Tokens anfordern, gibt die API keine Strings zurück, die die Persona repräsentieren.

Spielbezogene Rückruftokens

So rufen Sie die Speicherdaten-Tokens aus dem aktuellen Spiel ab: Rufen Sie die recallSessionId vom Client ab und übergeben Sie 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
}

Letztes Speicherdaten-Token für alle Spiele, die dem Entwicklerkonto gehören

Wenn Sie das letzte Token abrufen möchten, das in allen Spielen gespeichert ist, die dem Entwicklerkonto in der Google Play Console gehören, müssen Sie die 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 prü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 Speicherdaten-Tokens für eine bestimmte Liste von Spielen, die dem Entwicklerkonto gehören

Wenn Sie alle Tokens abrufen möchten, die mit einer Liste von Spielen verknüpft sind, die Ihrem Entwicklerkonto in der Google Play Console gehören, rufen Sie die recallSessionId vom Client ab und übergeben Sie sie an die gamesPlayerTokens API. 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 Erinnerungstoken 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();

Profilfreien Modus aktivieren

So aktivieren Sie die eingeschränkte Recall API-Funktionalität für Nutzer ohne PGS-Profile:

1. Aktivieren Sie die profillose Recall-Funktion für Ihr Play-Spieldienste-Projekt in der Play Console.
2. Lesen Sie die zusätzlichen Bedingungen, die weiter unten in diesem Abschnitt beschrieben werden.
3. Fügen Sie dem App-Manifest das folgende Metadaten-Tag hinzu:

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

Zusatzbedingungen

Zusätzlich zu den Nutzungsbedingungen für die Play-Spieldienste stimmen Sie zu, dass Sie, wenn Sie die Recall API für Nutzer ohne PGS-Profil verwenden, wodurch die Daten des Endnutzers an Google weitergegeben werden können, ohne dass dieser ein Play-Spieldienste-Profil hat, den Endnutzer vor der Weitergabe solcher Daten an Google entsprechend benachrichtigen müssen. Die Benachrichtigung muss Folgendes enthalten:

1. Ihre Freigabe der Daten für Google, um die Kontoverknüpfung mit Play Spiele zu ermöglichen.
2. Die Verfügbarkeit von Einstellungen zur Verwaltung dieser Freigabe, z. B. Play Spiele-Einstellungen
3. Die Verarbeitung dieser Daten unterliegt der Datenschutzerklärung von Google. Sie müssen die entsprechende Einwilligung der Endnutzer für die Weitergabe einholen, die allen anwendbaren rechtlichen Anforderungen entspricht.