App-Flip für Android

Wenn du eine OAuth 2.0-Implementierung hast, kannst du optional ein OAuth-basiertes App Flip konfigurieren. Dadurch 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 die Aktion smart home 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 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.

Diese Abbildung zeigt ein Beispiel für einen Zustimmungsbildschirm mit Zusatzinformationen zu den individuellen Anforderungen und Empfehlungen, die beim Entwerfen eines Zustimmungsbildschirms für Nutzer zu beachten sind.
Abbildung 1: Designrichtlinien für den Kontoverknüpfungsbildschirm.

OAuth-basiertes App-Flip einrichten

In den folgenden Abschnitten werden die Voraussetzungen für OAuth-basiertes App Flip beschrieben und Sie erfahren, wie Sie Ihr App Flip-Projekt in der Actions Console konfigurieren.

Smart-Home-Aktion erstellen und OAuth 2.0-Server einrichten

Bevor Sie App Flip konfigurieren können, sind folgende Schritte erforderlich:

  • 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 Aktionskonsole 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. Klicken Sie unter App für Kontoverknüpfung verwenden (optional) auf das Kästchen Für Android aktivieren.
  3. Füllen Sie die folgenden Felder aus:
    • App-ID: Die Anwendungs-ID ist eine eindeutige ID, die Sie für Ihre Anwendung festlegen.
    • App-Signatur: Android-Apps müssen mit einem öffentlichen Schlüsselzertifikat signiert sein, bevor sie installiert werden können. Weitere 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 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 muss der Nutzerautorisierungscode in deiner App so geändert werden, 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 auf der Console und in Ihrer App konfiguriert haben, können Sie App Flip auf Ihrem Mobilgerät testen. Sie können die Google Assistant App oder die Google Home App verwenden, um App Flip zu testen.

So testen Sie App Flip über die Assistant App:

  1. Gehen Sie zur Aktionskonsole und wählen Sie Ihr Projekt aus.
  2. Klicken Sie im oberen Navigationsbereich auf Testen.
  3. So lösen Sie die Kontoverknüpfung in der Assistant App aus:
    1. Öffnen Sie 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 deine Aktion aus der Liste der Anbieter aus. In der Liste wird das Präfix „[test]“ vorangestellt. Wenn Sie die Aktion [test] aus der Liste auswählen, sollte die 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. Gehen Sie zur Aktionskonsole und wählen Sie Ihr Projekt aus.
  2. Klicken Sie im oberen Navigationsbereich auf Testen.
  3. So lösen Sie den Kontoverknüpfungsvorgang 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 etwas eingerichtet?.
    5. Wähle in der Liste der Anbieter deine Smart-Home-Aktion aus. In der Liste wird das Präfix „[test]“ vorangestellt. Wenn Sie die Aktion [test] aus der Liste auswählen, sollte die App geöffnet werden.
    6. Prüfen Sie, ob Ihre App gestartet wurde, und testen Sie den Autorisierungsvorgang.
Zurück
Actions-Projekt erstellen
Weiter
Erkennen und synchronisieren