App Flip für iOS

Sobald du eine OAuth 2.0-Implementierung hast, kannst du optional die OAuth-basierte App Flip konfigurieren. Damit können deine iOS-Nutzer ihre Konten in deinem Authentifizierungssystem schneller mit ihren Google-Konten verknüpfen. In den folgenden Abschnitten wird beschrieben, wie Sie App Flip für Ihre Cloud-to-cloud-Integration unter iOS entwerfen und implementieren.

Gestaltungsrichtlinien

In diesem Abschnitt werden die Designanforderungen und ‑empfehlungen für den Zustimmungsbildschirm für die App-Flip-Kontoverknüpfung beschrieben. Nachdem Google Ihre App aufgerufen hat, zeigt Ihre App dem Nutzer den Zustimmungsbildschirm an.

Voraussetzungen

1. Du musst über eine Google-Autorisierungserklärung verfügen, z. B. „Nach der Verknüpfung hat Google die Berechtigung, deine Geräte zu steuern.“
2. Sie müssen dem Nutzer mitteilen, dass sein Konto mit Google verknüpft wird, nicht mit einem bestimmten Google-Produkt wie Google Home oder Google Assistant.
3. Sie müssen auf dem Einwilligungsbildschirm einen klaren Call-to-Action angeben und für die Verknüpfungsaktion die Formulierung „Zustimmen und verknüpfen“ verwenden. Das liegt daran, dass Nutzer wissen müssen, welche Daten sie mit Google teilen müssen, um ihre Konten zu verknüpfen.
4. Sie müssen Nutzern die Möglichkeit geben, zurückzugehen, die Verknüpfung abzulehnen oder zu kündigen, wenn sie sich gegen eine Verknüpfung entscheiden. Verwenden Sie die Formulierung „Abbrechen“ für die Aktion zum Abbrechen.
5. Sie müssen diesen Ablauf implementieren: Nachdem der Nutzer auf „Zustimmen und verknüpfen“ geklickt hat, müssen Sie ihm anzeigen, dass die Verknüpfung erfolgreich war, und ihn automatisch zur Google Home App zurückleiten. Der Nutzer sollte das verknüpfte Gerät jetzt in der Google Home App mit Ihrer Aktion sehen. Nachdem der Nutzer auf „Abbrechen“ geklickt hat, solltest du ihn zur Google Home App zurückleiten.

Empfehlungen

Wir empfehlen Folgendes:

1. Datenschutzerklärung von Google anzeigen Fügen Sie auf dem Zustimmungsbildschirm einen Link zur Datenschutzerklärung von Google ein.

2. Zu teilende Daten: Verwenden Sie eine klare und prägnante Sprache, um dem Nutzer mitzuteilen, welche seiner Daten Google benötigt und warum.

3. Möglichkeit, die Verknüpfung aufzuheben: Bieten Sie Nutzern eine Möglichkeit, die Verknüpfung aufzuheben, z. B. eine URL zu ihren Kontoeinstellungen auf Ihrer Plattform. Alternativ können Sie einen Link zu Google-Konto einfügen, über den Nutzer ihr verknüpftes Konto verwalten können.

4. Nutzerkonto ändern: Schlagen Sie Nutzern eine Methode vor, mit der sie ihr(e) Konto(s) wechseln können. Das ist besonders dann von Vorteil, wenn Nutzer mehrere Konten haben.

   • Wenn ein Nutzer den Zustimmungsbildschirm schließen muss, um das Konto zu wechseln, senden Sie einen behebaren Fehler an Google, damit sich der Nutzer mit OAuth-Verknüpfung und dem impliziten Ablauf im gewünschten Konto anmelden kann.

5. Fügen Sie Ihr Logo ein. Ihr Unternehmenslogo auf dem Zustimmungsbildschirm anzeigen Platzieren Sie Ihr Logo gemäß Ihren Style-Richtlinien. Wenn Sie auch das Google-Logo anzeigen möchten, lesen Sie den Abschnitt Logos und Marken.

Für OAuth-basiertes App Flip einrichten

In den folgenden Abschnitten werden die Voraussetzungen für OAuth-basiertes App-Flip und die Konfiguration Ihres App-Flip-Projekts in der Google Home Developer Console beschrieben.

Cloud-zu-Cloud-Integration erstellen und OAuth 2.0-Server einrichten

Bevor Sie App Flip konfigurieren können, müssen Sie Folgendes tun:

• Richten Sie einen OAuth 2.0-Server ein. Weitere Informationen zum Einrichten eines OAuth-Servers finden Sie unter OAuth 2.0-Server implementieren.
• Cloud-zu-Cloud-Integration erstellen Folgen Sie der Anleitung unter Cloud-zu-Cloud-Integration erstellen, um eine Integration zu erstellen.

App Flip in der Developer Console konfigurieren

Im folgenden Abschnitt wird beschrieben, wie Sie App Flip in der Developer Console konfigurieren.

1. Füllen Sie alle Felder unter OAuth-Clientinformationen aus. (Wenn App Flip nicht unterstützt wird, wird reguläres OAuth als Fallback verwendet.)
2. Setzen Sie unter App für die Kontoverknüpfung verwenden(optional) ein Häkchen bei Für iOS aktivieren.
3. Füllen Sie das Feld Universeller Link aus. Weitere Informationen zu universellen Links finden Sie unter Allowing Apps and Websites to Link to your Content.
4. Wenn Sie Ihren Client optional konfigurieren möchten, fügen Sie Bereiche hinzu und klicken Sie unter Client konfigurieren (optional) auf Bereich hinzufügen.
5. Klicken Sie auf Speichern.

Sie können jetzt mit dem nächsten Abschnitt fortfahren, um App Flip in Ihrer iOS-App zu implementieren.

App Flip in Ihren systemeigenen Apps implementieren

Wenn du App Flip implementieren möchtest, musst du den Nutzerautorisierungscode in deiner App so ändern, dass ein Deeplink von Google akzeptiert wird.

Bei der OAuth-basierten App-Flip-Verknüpfung (App Flip) wird Ihre iOS-App über eine Google-App geöffnet, damit der Nutzer der Google-App sein Konto einfacher verknüpfen kann. Sie müssen geringfügige Codeänderungen an Ihrer iOS-App vornehmen, um diese Funktion zu implementieren.

In diesem Dokument erfahren Sie, wie Sie Ihre iOS-App so ändern, dass sie App Flip unterstützt.

Beispiel testen

Die Beispiel-App für App-Flip zeigt eine App-Flip-kompatible Integration der Kontoverknüpfung unter iOS. Mit dieser App können Sie prüfen, wie Sie auf einen eingehenden App Flip-Universallink von mobilen Google-Apps reagieren.

Die Beispiel-App ist für die Integration in das App Flip-Testtool für iOS vorkonfiguriert. Mit diesem Tool können Sie die Integration Ihrer iOS-App in App Flip prüfen, bevor Sie die Kontoverknüpfung mit Google konfigurieren. Diese App simuliert den universellen Link, der von mobilen Google-Apps ausgelöst wird, wenn App Flip aktiviert ist.

Funktionsweise

Im Folgenden sind die Schritte aufgeführt, die die Google App und Ihre App bei App Flip ausführen:

1. Die Google App versucht, den universellen Link Ihrer App zu öffnen. Sie kann Ihre App öffnen, wenn sie auf dem Gerät des Nutzers installiert und mit dem universellen Link verknüpft ist. Weitere Informationen finden Sie unter Supporting Universal Links (Universelle Links unterstützen).

2. Ihre App prüft, ob die in der eingehenden URL codierten Parameter client_id und redirect_uri mit dem erwarteten universellen Google-Link übereinstimmen.

3. Ihre App fordert einen Autorisierungscode von Ihrem OAuth2-Server an. Am Ende dieses Ablaufs gibt Ihre App entweder einen Autorisierungscode oder einen Fehler an die Google App zurück. Dazu wird der universelle Link von Google mit angehängten Parametern für den Autorisierungscode oder den Fehler geöffnet.

4. Die Google App verarbeitet den eingehenden universellen Google-Link und fährt mit dem restlichen Ablauf fort. Wenn ein Autorisierungscode angegeben wird, wird die Verknüpfung sofort hergestellt. Der Tokenaustausch erfolgt von Server zu Server, genau wie beim browserbasierten OAuth-Verknüpfungsvorgang. Wenn ein Fehlercode zurückgegeben wird, wird der Verknüpfungsvorgang mit den alternativen Optionen fortgesetzt.

iOS-App für die Unterstützung von App-Flip anpassen

Wenn Sie App Flip unterstützen möchten, nehmen Sie die folgenden Codeänderungen an Ihrer iOS-App vor:

1. Verarbeiten Sie NSUserActivityTypeBrowsingWeb in Ihrem App-Delegat.
2. Erfassen Sie die Parameter redirect_uri und state aus der URL, um sie später zu verwenden.
3. Prüfen Sie, ob redirect_uri diesem Format entspricht:

   https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
   https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

4. Prüfen Sie, ob die Client-ID mit dem erwarteten Wert übereinstimmt. Verwenden Sie das folgende Codebeispiel:

   func application(_ application: UIApplication,
                    continue userActivity: NSUserActivity,
                    restorationHandler: @escaping ([Any]?) -> Void) -> Bool
   {
       guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let incomingURL = userActivity.webpageURL,
           let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
           let params = components.queryItems else {
               return false
       }
   
       if let clientId = params.filter({$0.name == "client_id"}).first?.value,
           let state = params.filter({$0.name == "state"}).first?.value,
           let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {
   
           // Save the redirect_uri and state for later...
   
           // Verify the client id
           return (clientId == GOOGLE_CLIENT_ID)
       } else {
           // Missing required parameters
           return false
       }
   }
   

5. Rufen Sie nach erfolgreicher Autorisierung den Weiterleitungs-URI mit dem Autorisierungscode auf. Verwenden Sie das folgende Codebeispiel:

   func returnAuthCode(code: String, state: String, redirectUri: String) {
       var redirectURL = URL(string: redirectUri)
       var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
   
       // Return the authorization code and original state
       let paramAuthCode = URLQueryItem(name: "code", value: code)
       let paramState = URLQueryItem(name: "state", value: state)
       components?.queryItems = [paramAuthCode, paramState]
       if let resultURL = components?.url {
           UIApplication.shared.open(
               resultURL,
               options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
               completionHandler: nil)
       }
   }
   

6. Wenn ein Fehler aufgetreten ist, hängen Sie stattdessen ein Fehlerergebnis an den Weiterleitungs-URI an. Verwenden Sie das folgende Codebeispiel:

   func returnError(redirectUri: String) {
       var redirectURL = URL(string: redirectUri)
       var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)
   
       // Return the authorization code and original state
       let paramError = URLQueryItem(name: "error", value: "invalid_request")
       let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
       components?.queryItems = [paramError, paramDescription]
       if let resultURL = components?.url {
           UIApplication.shared.open(
               resultURL,
               options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
               completionHandler: nil)
       }
   }
   

Abfrageparameter für den universellen Link Ihrer App

Wenn der universelle Link Ihrer App von der Google App geöffnet wird, enthält er die folgenden Suchparameter:

• client_id (String): Google-client_id, das für Ihre App registriert ist.
• scope (List of String): Eine Liste der angeforderten Bereiche, getrennt durch Leerzeichen.
• state (String): Eine Nonce, die von Google verwendet wird, um zu prüfen, ob das Autorisierungsergebnis eine Antwort auf die ausgehende Anfrage von Google ist.
• redirect_uri (String): Universeller Link von Google. Der „Flip“-URI zum Öffnen der Google App und zum Übergeben von Ergebnissen.

Suchparameter für den universellen Link von Google

Parameter, die verwendet werden, wenn das Autorisierungsergebnis erfolgreich zurückgegeben wird:

• code (String): Der Wert des Autorisierungscodes, falls verfügbar.
• state (String): Der genaue Wert, der vom eingehenden universellen Link empfangen wurde.

Parameter, die verwendet werden, wenn das Autorisierungsergebnis nicht erfolgreich zurückgegeben wird:

• error (String) mit den folgenden Werten:

  • cancelled: Ein behebbarer Fehler. Die Google App versucht, die Kontoverknüpfung über die Autorisierungs-URL durchzuführen. Beispiele hierfür sind, dass sich der Nutzer nicht anmelden kann, ein Gerät offline ist oder eine Verbindung wegen Zeitüberschreitung abgebrochen wird.
  • unrecoverable: Ein nicht behebbarer Fehler. Der Nutzer versucht beispielsweise, eine Verknüpfung mit einem deaktivierten Konto herzustellen.Die Google App bricht die Kontoverknüpfung ab.
  • invalid_request: Die Anfrageparameter sind ungültig oder fehlen. Dieser Fehler lässt sich beheben. Die Google App versucht, die Kontoverknüpfung über die Autorisierungs-URL durchzuführen.
  • access_denied: Der Nutzer lehnt die Einwilligungsanfrage ab. Dies ist ein nicht behebbarer Fehler. Die Google App bricht die Verknüpfung ab.

• error_description (String, optional): Eine nutzerfreundliche Fehlermeldung.

Bei allen Fehlertypen müssen Sie die Antwortdaten an die angegebene REDIRECT_URI zurückgeben, damit der entsprechende Fallback ausgelöst wird.

Autorisierungsendpunkt so ändern, dass App Flip unterstützt wird

Konfiguriere deine Plattform so, dass Anfragen über die App Flip-Weiterleitungs-URLs von Google akzeptiert werden:

• Google Home App

  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
  https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast
  

• Google Assistant App

  https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
  https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
  https://oauth-redirect.googleusercontent.com/a/com.google.OPA
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
  https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA
  

Für die Google Home app (GHA) verwendet die Smart-Home-Kontoverknüpfung die Weiterleitungs-URLs com.google.Chromecast. Achte darauf, dass dein Autorisierungsserver diese Weiterleitungs-URLs zulässt.

Prüfen Sie, ob client_id und die durch den Parameter redirect_uri angegebene URL mit den erwarteten Werten übereinstimmen, wenn eine Anfrage eingeht. Wenn die Clientüberprüfung fehlschlägt, geben Sie den Fehler invalid_request an den redirect_uri zurück.

App Flip auf deinem Gerät testen

Nachdem du eine Cloud-to-Cloud-Integration erstellt und App Flip in der Console und in deiner App konfiguriert hast, kannst du App Flip auf deinem Mobilgerät testen. Du kannst die Google Home App verwenden, um App Flip zu testen.

So testen Sie App Flip in der Google Home-App:

1. Rufen Sie die Developer Console auf und wählen Sie Ihr Projekt aus.
2. Gehe zu Cloud-to-Cloud > Test.
3. Kontoverknüpfung über die Home App starten:
1. Öffnen Sie die Google Home app (GHA).
2. Klicken Sie auf den Button +.
3. Klicken Sie auf Gerät einrichten.
4. Klicken Sie auf Haben Sie bereits etwas eingerichtet?.
5. Wähle deine Cloud-to-Cloud-Integration aus der Liste der Anbieter aus. In der Liste wird ihm „[test]“ vorangestellt. Wenn Sie Ihre [Test]-Integration aus der Liste auswählen, sollte Ihre App geöffnet werden.
6. Prüfen Sie, ob Ihre App gestartet wurde, und beginnen Sie mit dem Testen des Autorisierungsablaufs.