App Flip für Android

Sobald du eine OAuth 2.0-Implementierung hast, kannst du optional die OAuth-basierte App Flip konfigurieren. Damit können deine Android-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 in Android 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 unter Kontoverknüpfung alle Pflichtfelder(*) aus. (Wenn App Flip nicht unterstützt wird, wird reguläres OAuth als Fallback verwendet.)
2. Gib eine URL für die Cloud-Ausführungs-URL an. Die Cloud-Ausführungs-URL wird verwendet, um deine Smart-Home-Intents zu verarbeiten. Lokale Ausführung
3. Setzen Sie unter App Flip (optional) ein Häkchen bei Android-App.
4. Füllen Sie die folgenden Felder aus:
• Anwendungs-ID: Die Anwendungs-ID ist eine eindeutige ID, die Sie für Ihre Anwendung festlegen.
• App-Signatur: Android-Apps müssen mit einem Public-Key-Zertifikat signiert werden, bevor sie installiert werden können. Informationen zum Abrufen der App-Signatur finden Sie unter Client authentifizieren.
• Autorisierungsintent Geben Sie in diesem Feld einen String ein, der die Intent-Aktion angibt.
5. Wenn Sie Ihren Client optional konfigurieren möchten, fügen Sie Bereiche hinzu und klicken Sie unter Bereiche (optional) auf Bereich hinzufügen.
6. Wenn Ihr Client dies erfordert, wählen Sie Zulassen, dass Google die Client-ID und den Clientschlüssel über den Header für die HTTP-Basic-Authentifizierung überträgt aus.

Sie können jetzt mit dem nächsten Abschnitt fortfahren, um App Flip in Ihrer Android-Anwendung 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 Android-App in den Ablauf der Google-Kontoverknüpfung eingefügt. Bei einem herkömmlichen Ablauf zur Kontoverknüpfung muss der Nutzer seine Anmeldedaten im Browser eingeben. Bei der Verwendung von App Flip wird die Anmeldung des Nutzers auf Ihre Android-App verschoben, sodass Sie vorhandene Autorisierungen nutzen können. Wenn der Nutzer in deiner App angemeldet ist, muss er seine Anmeldedaten nicht noch einmal eingeben, um sein Konto zu verknüpfen. Für die Implementierung von App Flip in Ihrer Android-App sind nur minimale Codeänderungen erforderlich.

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

Beispiel testen

Die Beispiel-App für die App-Flip-Verknüpfung zeigt eine App-Flip-kompatible Integration der Kontoverknüpfung unter Android. Mit dieser App können Sie prüfen, wie auf einen eingehenden App Flip-Intent von mobilen Google-Apps reagiert werden soll.

Die Beispiel-App ist für die Integration in das App Flip-Testtool für Android vorkonfiguriert. Mit diesem Tool kannst du die Integration deiner Android-App in App Flip prüfen, bevor du die Kontoverknüpfung mit Google konfigurierst. Diese App simuliert den Intent, der von mobilen Google-Apps ausgelöst wird, wenn App Flip aktiviert ist.

Funktionsweise

Die folgenden Schritte sind erforderlich, um eine App-Flip-Integration durchzuführen:

1. Die Google App prüft anhand des Paketnamens, ob deine App auf dem Gerät installiert ist.
2. Die Google App verwendet eine Paketsignaturprüfung, um zu bestätigen, dass die installierte App die richtige App ist.
3. Die Google App erstellt einen Intent, um eine bestimmte Aktivität in Ihrer App zu starten. Dieser Intent enthält zusätzliche Daten, die für die Verknüpfung erforderlich sind. Außerdem wird geprüft, ob Ihre App App Flip unterstützt, indem dieser Intent über das Android-Framework aufgelöst wird.
4. Ihre App prüft, ob die Anfrage von der Google App stammt. Dazu werden die Paketsignatur und die angegebene Client-ID geprüft.
5. Ihre App fordert einen Autorisierungscode von Ihrem OAuth 2.0-Server an. Am Ende dieses Ablaufs wird entweder ein Autorisierungscode oder ein Fehler an die Google App zurückgegeben.
6. Die Google App ruft das Ergebnis ab und fährt mit der Kontoverknüpfung fort. Wenn ein Autorisierungscode bereitgestellt wird, erfolgt der Tokenaustausch zwischen Servern, genau wie beim browserbasierten OAuth-Verknüpfungsvorgang.

Android-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 Android-App vor:

1. Fügen Sie Ihrer AndroidManifest.xml-Datei einen <intent-filter> mit einem Aktionsstring hinzu, der dem Wert entspricht, den Sie im Feld App Flip Intent eingegeben haben.

   <activity android:name="AuthActivity">
     <!-- Handle the app flip intent -->
     <intent-filter>
       <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
       <category android:name="android.intent.category.DEFAULT"/>
     </intent-filter>
   </activity>
   

2. Signatur der aufrufenden App validieren

   Der Paketname und die Signatur müssen mit allen Google-Apps übereinstimmen, die Nutzer für die Kontoverknüpfung verwenden können. Wenn Sie beispielsweise eine Verknüpfung mit der Google Home App und der Google App herstellen möchten, fügen Sie deren Paketnamen und Signaturen hinzu:

   • Paketname: com.google.android.apps.chromecast.app
   • Ursprüngliches SHA-256-Abstammungszertifikat: 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
   • SHA-256-Zertifikat für die rotierte Play App-Signatur: 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

   und

   • Paketname: com.google.android.googlequicksearchbox
   • Unterschrift: F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

   Anfragen zur Smart-Home-Verknüpfung werden direkt vom Google Home app (GHA) initiiert. Wenn Ihre Anwendung Aufrufer einschränkt und zuvor nur die Google Suche App zugelassen hat, müssen Sie com.google.android.apps.chromecast.app und die zugehörigen SHA-256-Zertifikate Ihrer Zulassungsliste hinzufügen, damit App Flip weiterhin funktioniert.

   private fun verifyFingerprint(
       expectedPackage: String,
       expectedFingerprints: List<String>
   ): Boolean {
       val callingPackage = callingActivity?.packageName ?: return false
       if (callingPackage != expectedPackage) return false
       return expectedFingerprints.any { hex ->
           val sha256Bytes =
               hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
           packageManager.hasSigningCertificate(
               callingPackage,
               sha256Bytes,
               PackageManager.CERT_INPUT_SHA256
           )
       }
   }
   

3. Extrahieren Sie die Client-ID aus den Intent-Parametern und prüfen Sie, ob die Client-ID mit dem erwarteten Wert übereinstimmt.

   private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
   private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
   // Original lineage certificate (3D:7A...) and active rotated
   // Play App Signing certificate (5A:AD...)
   private val EXPECTED_FINGERPRINTS = listOf(
       "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
       "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
   )
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {
   
           // ...authorize the user...
       }
   }
   

4. Nach erfolgreicher Autorisierung wird der resultierende Autorisierungscode an Google zurückgegeben.

   // Successful result
   val data = Intent().apply {
       putExtra("AUTHORIZATION_CODE", authCode)
   }
   setResult(Activity.RESULT_OK, data)
   finish()
   

5. Wenn ein Fehler aufgetreten ist, geben Sie stattdessen ein Fehlerergebnis zurück.

   // Error result
   val error = Intent().apply {
       putExtra("ERROR_TYPE", 1)
       putExtra("ERROR_CODE", 1)
       putExtra("ERROR_DESCRIPTION", "Invalid Request")
   }
   setResult(-2, error)
   finish()
   

Inhalt des Start-Intents

Der Android-Intent, mit dem Ihre App gestartet wird, enthält die folgenden Felder:

• CLIENT_ID (String): Google client_id, die unter Ihrer App registriert ist.
• SCOPE (String[]): Eine Liste der angeforderten Bereiche.
• REDIRECT_URI (String): Die Weiterleitungs-URL.

Inhalt der Antwortdaten

Die an die Google App zurückgegebenen Daten werden in Ihrer App durch Aufrufen von setResult() festgelegt. Diese Daten umfassen Folgendes:

• AUTHORIZATION_CODE (String): Der Wert des Autorisierungscodes.
• resultCode (int): Gibt an, ob der Prozess erfolgreich war oder nicht, und kann einen der folgenden Werte annehmen:
  • Activity.RESULT_OK: Gibt an, dass der Vorgang erfolgreich war. Ein Autorisierungscode wird zurückgegeben.
  • Activity.RESULT_CANCELLED: Ein behebbarer Fehler. Signalisiert, dass der Nutzer den Vorgang abgebrochen hat. In diesem Fall versucht die Google App noch einmal, die Kontoverknüpfung über Ihre Autorisierungs-URL durchzuführen.
  • -2: Gibt an, dass ein Fehler aufgetreten ist. Im Folgenden werden verschiedene Arten von Fehlern beschrieben.
• ERROR_TYPE (int): Der Fehlertyp, der einen der folgenden Werte annimmt:
  • 1: Behebbarer Fehler: Die Google App versucht, die Kontoverknüpfung über die Autorisierungs-URL durchzuführen.
  • 2: Nicht behebbarer Fehler: Die Google App bricht die Kontoverknüpfung ab.
  • 3: Ungültige oder fehlende Anfrageparameter.
• ERROR_CODE (int): Eine Ganzzahl, die die Art des Fehlers darstellt. Die Bedeutung der einzelnen Fehlercodes finden Sie in der Tabelle der Fehlercodes.

• ERROR_DESCRIPTION (String, optional): Eine menschenlesbare Statusmeldung, die den Fehler beschreibt.

Ein Wert für AUTHORIZATION_CODE wird erwartet, wenn resultCode == Activity.RESULT_OK. In allen anderen Fällen muss der Wert für AUTHORIZATION_CODE leer sein. Wenn resultCode == -2, muss der Wert ERROR_TYPE angegeben werden.

Tabelle mit Fehlercodes

In der folgenden Tabelle sind die verschiedenen Fehlercodes aufgeführt und es wird angegeben, ob es sich um einen behebbaren oder nicht behebbaren Fehler handelt:

Fehlercode	Bedeutung	Wiederherstellbar	Uneinbringlich
1	INVALID_REQUEST	✔
2	NO_INTERNET_CONNECTION		✔
3	OFFLINE_MODE_ACTIVE	✔
4	CONNECTION_TIMEOUT	✔
5	INTERNAL_ERROR	✔
6	AUTHENTICATION_SERVICE_UNAVAILABLE		✔
8	CLIENT_VERIFICATION_FAILED	✔
9	INVALID_CLIENT	✔
10	INVALID_APP_ID	✔
11	INVALID_REQUEST	✔
12	AUTHENTICATION_SERVICE_UNKNOWN_ERROR		✔
13	AUTHENTICATION_DENIED_BY_USER		✔
14	CANCELLED_BY_USER		✔
15	FAILURE_OTHER		✔
16	USER_AUTHENTICATION_FAILED	✔

Bei allen Fehlercodes musst du das Fehlerergebnis über setResult zurückgeben, damit der entsprechende Fallback ausgelöst wird.

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.