Recall API

Mit der Recall API können Spiele Verknüpfungen zwischen Nutzern der Google Play-Spieldienste (PGS) und ihren In-Game-Konten verwalten, indem sie Speicherdaten-Tokens auf Google-Servern speichern. Hier ein Beispielszenario für die Verwendung der Recall API:

1. Ein Nutzer spielt ein Spiel, in dem der Entwickler ein Identitätssystem verwendet, um den Fortschritt der Nutzer zu verfolgen. Er verwendet die Play-Spieldienste parallel zu anderen Authentifizierungsmethoden, um Nutzer in seinem Spiel anzumelden. In diesem Beispiel ist ein Nutzer in seinem PGS-Konto Laura angemeldet und erstellt mit dem Identitätssystem des Entwicklers ein In-Game-Konto namens Racer94. Während der Nutzer das Spiel spielt, synchronisiert der Gameserver des Entwicklers seinen Fortschritt.

   

2. Der Entwickler speichert separat ein Speicherdaten-Token bei Google, das dem In-Game-Konto des Nutzers entspricht. Google speichert dieses Speicherdaten-Token automatisch im Play-Spieldienste-Profil des Nutzers.

   

3. Der Nutzer entscheidet sich nun, das Spiel zum ersten Mal über Google Play Spiele auf dem PC zu spielen. Der Nutzer wird automatisch mit seinem PGS-Konto angemeldet und der Spieleclient prüft, ob für diesen PGS-Nutzer ein Fortschritt verfügbar ist. Der Gameserver fragt dann bei Google an, ob es Tokens für dieses PGS-Konto gibt. Da es diese gibt, sendet Google das Speicherdaten-Token zurück. Der Gameserver verwendet dieses Token, um das zugehörige Konto „Racer94“ des Nutzers zu finden und seinen Fortschritt wiederherzustellen. Da die Anmeldung mit den Play-Spieldiensten reibungslos erfolgt, wird der Fortschritt des Nutzers von der App wiederhergestellt, ohne dass der Nutzer einen Nutzernamen oder ein Passwort eingeben muss. Außerdem kann der Entwickler die Anmeldung über die Play-Spieldienste mit seinem bestehenden Identitätssystem verwenden und sich darauf verlassen, dass Google die Verknüpfung zwischen dem Spielfortschritt und dem Konto der Play-Spieldienste speichert.

   

Wie im Beispiel oben zu sehen ist, gibt es zwei Hauptaktionen, die von der Recall API ausgeführt werden:

• Das Token wird bei Google gespeichert, wenn sich ein Nutzer mit einem der In-Game-Konten anmeldet.

• Das Token wird für einen Nutzer abgerufen, um seine In-Game-Konten wiederherzustellen.

Zusätzlich zu Speicherdaten-Tokens erfordert die Recall API auch eine stabile Kennzeichnung, die dem In-Game-Konto entspricht, die sogenannte Identität, um Kardinalitätsbeschränkungen zu erzwingen. Sie können sich eine Identität als das Label vorstellen, das das In-Game-Konto des Nutzers im Identitätssystem des Entwicklers repräsentiert. Das Speicherdaten-Token ist ein Schlüssel, mit dem das In-Game-Konto des Nutzers im Spiel wiederhergestellt wird. Die Werte für Identität und Tokens dürfen nicht für verschiedene PGS-Projekte wiederverwendet werden. Speicherdaten-Tokens können sich im Laufe der Zeit ändern, aber eine Identität sollte gemäß dem In-Game-Konto des Nutzers stabil sein.

Regeln zur Kardinalität

Die Recall API erzwingt eine 1:1-Beziehung zwischen PGS-Profilen und In-Game-Konten (als Kardinalitätsregeln bezeichnet). Eine Identität kann nur mit einem PGS-Profil verknüpft werden und ein PGS-Profil kann nur mit einer Identität verknüpft werden. Die Identität wird als stabile Kennzeichnung für ein In-Game-Konto verwendet, da sich Speicherdaten-Tokens im Laufe der Zeit ändern können.

Die mit einem PGS-Profil verknüpfte Identität kann ebenfalls im Laufe der Zeit geändert werden, wenn verschiedene In-Game-Konten mit dem PGS-Profil verknüpft werden.

Technische Abläufe zum Speichern und Abrufen der Speicherdaten-Tokens

In diesem Abschnitt wird der technische Ablauf zwischen dem Spieleclient und den Servern mit Google-Servern beim Speichern und Abrufen von Speicherdaten-Tokens beschrieben.

Schritt 1: PGS-Nutzer anmelden und Sitzungs-ID abrufen

Das Spiel initialisiert das PGS SDK und versucht, den Nutzer mit PGS anzumelden.

Wenn der Nutzer angemeldet ist, fordern Sie eine Sitzungs‑ID vom Games SDK auf dem Spieleclient und ein OAuth 2.0-Token vom OAuth-Backend von Google an. Die Sitzungs-ID und die OAuth 2.0-Tokens werden für die Kommunikation mit dem Google Games-Backend verwendet.

Schritt 2: Verfügbare Speicherdaten-Tokens abrufen

Fordern Sie alle zugehörigen Speicherdaten-Tokens für das Konto des PGS-Nutzers an. Wenn ein Token vorhanden ist, fahren Sie mit Schritt 3a fort und stellen Sie den Fortschritt wieder her. Wenn es sich um einen neuen Nutzer handelt und kein Token vorhanden ist, fahren Sie mit Schritt 3b fort und speichern Sie ein neues Token.

Schritt 3a: Wenn ein Token vorhanden ist, Fortschritt wiederherstellen

Wenn ein Token vorhanden ist, rufen Sie es ab, entschlüsseln Sie es und stellen Sie die Nutzerdaten wieder her.

Schritt 3b: Wenn kein Token vorhanden ist, Token speichern

Da kein Token vorhanden ist, wird kein Fortschritt wiederhergestellt. Der Nutzer meldet sich mit dem Identitätssystem des Entwicklers an oder erstellt ein neues Konto, falls noch keines vorhanden ist. Hinweis: Hierbei handelt es sich nicht um die Anmeldung mit den Play-Spieldiensten (die bereits erfolgt ist), sondern mit dem Identitätssystem eines Entwicklers außerhalb der Play-Spieldienste.

Erstellen Sie ein verschlüsseltes Speicherdaten-Token, in dem das In-Game-Konto des Nutzers codiert ist, und senden Sie es zusammen mit der Sitzungs‑ID und dem OAuth 2.0-Token an Google. An diesem Punkt stellt Google eine Verknüpfung zwischen dem gesendeten Speicherdaten-Token und dem PGS-Konto des Spielers her.

Abläufe für Nutzer ohne PGS-Profil

Sie können Speicherdaten-Tokens für einen Nutzer speichern, der noch kein PGS-Profil erstellt hat, indem Sie den Modus ohne Profil verwenden. Es gibt jedoch zwei wichtige Einschränkungen:

• Sie können keine Tokens für Nutzer ohne Play-Spieldienste-Profil abrufen. Die Profilerstellung wird automatisch ausgelöst, wenn der Nutzer versucht, sich auf einem zweiten Gerät mit Play-Spieldiensten in Ihrem Spiel anzumelden.
• Sie müssen zusätzliche Richtlinien einhalten, um sicherzustellen, dass Sie einen geeigneten Hinweis mit den folgenden Informationen haben und die entsprechende Einwilligung der Endnutzer einholen:
  • Sie geben die Daten an Google weiter, um die Funktion zur Verknüpfung von Play Spiele-Konten zu aktivieren.
  • Die Verfügbarkeit von Einstellungen zur Verwaltung dieser Freigabe, z. B. Play Spiele-Einstellungen
  • Die Verarbeitung dieser Daten unterliegt der Datenschutzerklärung von Google.

Token- und Identität-Paar speichern

1. Ein Nutzer ohne PGS-Profil öffnet ein Spiel, in dem die profillose Recall-Funktion aktiviert ist.
2. Das Games SDK löst eine automatische Anmeldung aus, die fehlschlägt, weil der Nutzer kein PGS-Profil hat.
3. Das Games SDK zeigt eine Snackbar an, in der der Nutzer darüber informiert wird, dass das Spiel in Google integriert ist. Diese Snackbar ist interaktiv – der Nutzer kann die Recall-Funktion deaktivieren, bis ein Profil erstellt wird.
4. Das Spiel fordert den Zugriff auf die Recall-Funktion an. Beachten Sie, dass die Play-Spieldienste Recall-Zugriffsanfragen ablehnen, wenn auf dem Gerät Play-Spieldienste-Profile vorhanden sind oder wenn auf dem Gerät keine Google-Konten vorhanden sind. In diesem Fall sollte das Spiel ohne PGS fortgesetzt werden.
5. Nachdem sich der Nutzer mit einem Konto im Spiel angemeldet hat, erstellt das Spiel ein Token- und Identität-Paar für den Nutzer, das seinem Konto im Spiel entspricht. Das Spiel speichert dieses Paar bei Google. Das Spiel speichert möglicherweise später weitere Tokens, wenn sich der Nutzer in anderen In-Game-Konten anmeldet.

Spiel auf einem neuen Gerät starten

1. Ein Nutzer ohne Play-Spieldienste-Profil öffnet ein Spiel, für das die profillose Recall-Funktion auf einem Gerät aktiviert ist.
2. Das Spiel zeichnet ein Speicherdaten-Token ohne Profil auf, wie unter Token- und Identität-Paar speichern beschrieben.
3. Der Nutzer öffnet dasselbe Spiel auf einem anderen Gerät, auf dem dasselbe Konto eingerichtet ist.
4. Das Games SDK löst die Profilerstellung aus. Der Nutzer kann zuvor gespeicherte Speicherdaten-Tokens prüfen und ablehnen. Der Nutzer erstellt zu diesem Zeitpunkt ein Play-Spieldienste-Profil.
5. Die automatische Anmeldung bei PGS wird abgeschlossen und das Spiel erhält den authentifizierten Status.
6. Das Spiel ruft wie gewohnt Speicherdaten-Tokens für den Nutzer ab.

Nächste Schritte

Folgen Sie dieser Anleitung, um die Recall API in Ihren Client und Gameserver einzubinden.