App-Flip für Android

Wenn Sie eine OAuth 2.0-Implementierung haben, können Sie optional den OAuth-basierten App Flip, which allows your Android users to more quickly link their accounts in your authentication system to their Google accounts. The following sections describe how to design and implement App Flip for your smart home Action. konfigurieren

Gestaltungsrichtlinien

In diesem Abschnitt werden die Designanforderungen und Empfehlungen für den Zustimmungsbildschirm für die App-Flip-Kontoverknüpfung beschrieben. Nachdem Google deine App aufgerufen hat, wird dem Nutzer der Zustimmungsbildschirm angezeigt.

Voraussetzungen

1. Sie müssen angeben, dass das Konto des Nutzers mit Google verknüpft wird, und nicht mit einem bestimmten Google-Produkt wie Google Home oder Google Assistant.

Empfehlungen

Wir empfehlen Folgendes:

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

2. Zu teilende Daten. Verwenden Sie eine klare und präzise Sprache, um dem Nutzer mitzuteilen, welche Daten Google erhebt und warum.

3. Klarer Call-to-Action Geben Sie auf dem Zustimmungsbildschirm einen klaren Call-to-Action an, etwa „Zustimmen und verknüpfen“. Das liegt daran, dass Nutzer verstehen müssen, welche Daten sie für die Verknüpfung mit Google freigeben müssen, um ihr Konto zu verknüpfen.

4. Kündigung möglich. Bieten Sie Nutzern die Möglichkeit, zurückzugehen oder den Vorgang abzubrechen, falls sie dies nicht möchten.

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

6. Berechtigung zum Ändern des Nutzerkontos Schlagen Sie eine Methode vor, mit der Nutzer ihre Konten wechseln können. Das ist besonders hilfreich, wenn Nutzer in der Regel mehrere Konten haben.

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

7. Logo hinzufügen Ihr Unternehmenslogo auf dem Zustimmungsbildschirm anzeigen Halten Sie sich dabei an die Stilrichtlinien. Wenn Sie auch das Google-Logo verwenden möchten, finden Sie entsprechende Informationen unter 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 Actions Console beschrieben.

Smart-Home-Aktion 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.
• Erstellen Sie eine Aktion. Folgen Sie der Anleitung unter Aktionen erstellen, um eine Aktion zu erstellen.

App-Flip in der Actions Console konfigurieren

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

1. Füllen Sie alle Felder unter OAuth-Client-Informationen aus. Wenn App Flip nicht unterstützt wird, wird reguläres OAuth als Fallback verwendet.
2. Klicken Sie unter App für die Kontoverknüpfung verwenden (optional) auf das Kästchen Für Android aktivieren.
3. 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 sein, bevor sie installiert werden können. Informationen zum Abrufen der Anwendungssignatur finden Sie unter Client authentifizieren.
• Autorisierungsabsicht: Geben Sie in dieses Feld einen String ein, der die Intent-Aktion angibt.
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.

App-Flip in Android-Apps implementieren

Zur Implementierung von App Flip musst du den Nutzerautorisierungscode in deiner App so ändern, dass ein Deeplink von Google akzeptiert wird.

Durch OAuth-basierte App-Flip-Verknüpfungen (App Flip) wird Ihre Android-App in den Google-Kontoverknüpfungsvorgang eingefügt. Bei einer herkömmlichen Kontoverknüpfung müssen Nutzer ihre Anmeldedaten im Browser eingeben. Durch die Verwendung von App Flip wird die Nutzeranmeldung in Ihrer Android-App verzögert, sodass Sie vorhandene Autorisierungen nutzen können. Wenn der Nutzer bei Ihrer Anwendung angemeldet ist, muss er seine Anmeldedaten nicht noch einmal eingeben, um sein Konto zu verknüpfen. Zur Implementierung von App Flip in Ihrer Android-App ist eine minimale Menge von Codeänderungen erforderlich.

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

Beispiel ansehen

Mit der Beispiel-App „App-Flip“ können Sie eine mit App Flip kompatible Kontoverknüpfungs-App unter Android demonstrieren. Mit dieser App können Sie prüfen, wie auf eingehende App Flip-Intents von mobilen Google-Apps reagiert wird.

Die Beispiel-App ist für die Integration in das App Flip-Testtool für Android vorkonfiguriert, mit dem Sie die Einbindung Ihrer Android-App in AppFlip überprüfen können, bevor Sie die Kontoverknüpfung mit Google konfigurieren. Diese App simuliert die Absicht, die von mobilen Google-Apps ausgelöst wird, wenn App Flip aktiviert ist.

Funktionsweise

Die folgenden Schritte sind für die Einbindung von App Flip erforderlich:

1. Die Google App prüft anhand ihres Paketnamens, ob deine App auf dem Gerät installiert ist.
2. Die Google App prüft anhand einer Paketsignatur, ob die installierte App die richtige 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. Hierzu wird dieser Intent über das Android-Framework aufgelöst.
4. Ihre App prüft, ob die Anfrage von der Google App stammt. Dazu prüft Ihre App die Paketsignatur und die angegebene Client-ID.
5. Ihre App fordert einen Autorisierungscode von Ihrem OAuth 2.0-Server an. Am Ende dieses Vorgangs wird ein Autorisierungscode oder ein Fehler an die Google App zurückgegeben.
6. Die Google App ruft das Ergebnis ab und setzt die Kontoverknüpfung fort. Wenn ein Autorisierungscode angegeben wird, erfolgt der Tokenaustausch von Server zu Server, genau wie bei der browserbasierten OAuth-Verknüpfung.

Android-App so ändern, dass sie App Flip unterstützt

Um App Flip zu unterstützen, nehmen Sie die folgenden Codeänderungen in Ihrer Android-App vor:

1. Fügen Sie der Datei AndroidManifest.xml eine <intent-filter> mit einem Aktionsstring hinzu, der dem Wert entspricht, den Sie in das 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.

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

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 = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...authorize the user...
       }
   }
   

4. Geben Sie bei erfolgreicher Autorisierung den resultierenden Autorisierungscode an Google zurück.

   // 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 ist unter deiner App registriert.
• 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. Zu diesen Daten gehören:

• AUTHORIZATION_CODE (String): Der Autorisierungscodewert.
• resultCode (int): Gibt den Erfolg oder Fehler des Prozesses an und verwendet einen der folgenden Werte:
  • Activity.RESULT_OK: Zeigt an, dass der Vorgang erfolgreich war. Es wird ein Autorisierungscode zurückgegeben.
  • Activity.RESULT_CANCELLED: Zeigt an, dass der Nutzer den Prozess abgebrochen hat. In diesem Fall versucht die Google App, die Kontoverknüpfung mit deiner 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: Wiederherstellbarer Fehler: Die Google App versucht, die Kontoverknüpfung über die Autorisierungs-URL durchzuführen.
  • 2: nicht behebbarer Fehler: Die Kontoverknüpfung wird von der Google App abgebrochen.
  • 3: Die Anfrageparameter sind ungültig oder fehlen.
• ERROR_CODE (int): Eine Ganzzahl, die die Art des Fehlers darstellt. Die einzelnen Fehlercodes finden Sie in der Tabelle der Fehlercodes.

• ERROR_DESCRIPTION (String, optional): Eine für Menschen lesbare Statusmeldung zur Beschreibung des Fehlers.

Ein Wert für AUTHORIZATION_CODE ist zu erwarten, wenn resultCode == Activity.RESULT_OK. In allen anderen Fällen muss der Wert für AUTHORIZATION_CODE leer sein. Wenn resultCode == -2 angegeben ist, wird der Wert ERROR_TYPE wahrscheinlich ausgefüllt.

Tabelle der Fehlercodes

In der folgenden Tabelle sehen Sie die verschiedenen Fehlercodes und Informationen dazu, ob es sich um einen behebbaren oder nicht behebbaren Fehler handelt:

Fehlercode	Bedeutung	Wiederherstellbar	Nicht wiederherstellbar
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	✔

Für alle Fehlercodes müssen Sie das Fehlerergebnis über setResult zurückgeben, damit das entsprechende Fallback ausgelöst wird.

App-Flip auf Ihrem Gerät testen

Nachdem Sie eine Aktion erstellt und App Flip in der Console und in Ihrer App konfiguriert haben, können Sie App Flip auf Ihrem Mobilgerät testen. Du kannst die App mit der Google Assistant App oder der Google Home App testen.

So testen Sie App Flip über die Assistant App:

1. Rufen Sie die Actions Console auf und wählen Sie Ihr Projekt aus.
2. Klicken Sie im oberen Navigationsbereich auf Test.
3. So lösen Sie die Kontoverknüpfung in der Assistant App aus:
1. Öffne die Google Assistant App.
2. Klicken Sie auf Einstellungen.
3. Klicken Sie auf dem Tab „Assistant“ auf Smart-Home-Steuerung.
4. Klicken Sie auf Hinzufügen(+).
5. Wähle in der Liste der Anbieter deine Aktion aus. Sie hat in der Liste das Präfix [test]. Wenn du deine [test]-Aktion aus der Liste auswählst, sollte deine App geöffnet werden.
6. Prüfen Sie, ob Ihre App gestartet wurde, und testen Sie den Autorisierungsvorgang.

So testen Sie App Flip über die Home App:

1. Rufen Sie die Actions Console auf und wählen Sie Ihr Projekt aus.
2. Klicken Sie im oberen Navigationsbereich auf Test.
3. So lösen Sie die Kontoverknüpfung in der Home App aus:
1. Öffnen Sie die Google Home App.
2. Klicken Sie auf die Schaltfläche +.
3. Klicken Sie auf Gerät einrichten.
4. Klicken Sie auf Du hast bereits Geräte eingerichtet?
5. Wähle in der Liste der Anbieter deine Smart-Home-Aktion aus. Sie hat in der Liste das Präfix [test]. Wenn du deine [test]-Aktion aus der Liste auswählst, sollte deine App geöffnet werden.
6. Prüfen Sie, ob Ihre App gestartet wurde, und testen Sie den Autorisierungsvorgang.