App Flip per Android

Una volta implementato OAuth 2.0, puoi facoltativamente configurare App Flip basato su OAuth, che consente agli utenti di Android di collegare più rapidamente i propri account nel tuo sistema di autenticazione ai propri Account Google. Le sezioni seguenti descrivono come progettare e implementare App Flip per l'integrazione di Cloud-to-cloud su Android.

Istruzioni sul design

Questa sezione descrive i requisiti e i consigli di progettazione per la schermata di consenso per il collegamento dell'account App Flip. Dopo che Google chiama la tua app, quest'ultima mostra la schermata di consenso all'utente.

Requisiti

  1. Devi avere una dichiarazione di autorizzazione di Google, ad esempio "Una volta collegato, Google avrà l'autorizzazione per controllare i tuoi dispositivi".
  2. Devi comunicare che l'account dell'utente viene collegato a Google, non a un prodotto Google specifico, come Google Home o l'Assistente Google.
  3. Devi indicare un invito all'azione chiaro nella schermata del consenso e utilizzare la dicitura "Accetta e collega" per l'azione di collegamento. Questo perché gli utenti devono capire quali dati sono tenuti a condividere con Google per collegare i propri account.
  4. Devi fornire agli utenti un modo per tornare indietro, negare o annullare se scelgono di non collegare gli account. Utilizza la dicitura "Annulla" per l'azione di annullamento.
  5. Devi implementare questo flusso di lavoro: dopo aver fatto clic su "Accetta e collega", devi mostrare l'esito positivo del collegamento e reindirizzare automaticamente l'utente all'app Google Home. L'utente dovrebbe ora vedere il dispositivo collegato nell'app Google Home con la tua azione. Dopo aver fatto clic su "Annulla", devi reindirizzare l'utente all'app Google Home.

Consigli

Ti consigliamo di procedere come segue:

  1. Visualizza le Norme sulla privacy di Google. Includi un link alle Norme sulla privacy di Google nella schermata per il consenso.

  2. Dati da condividere. Utilizza un linguaggio chiaro e conciso per comunicare all'utente quali dati di sua proprietà sono richiesti da Google e perché.

  3. Possibilità di scollegare. Offri agli utenti un meccanismo per scollegare l'account, ad esempio un URL alle impostazioni dell'account sulla tua piattaforma. In alternativa, puoi includere un link all'Account Google in cui gli utenti possono gestire il proprio account collegato.

  4. Possibilità di cambiare account utente. Suggerisci un metodo per consentire agli utenti di cambiare i propri account. Ciò è particolarmente utile se gli utenti tendono ad avere più account.

    • Se un utente deve chiudere la schermata del consenso per cambiare account, invia un errore recuperabile a Google in modo che l'utente possa accedere all'account desiderato con il collegamento OAuth e il flusso implicito.

  5. Includi il tuo logo. Mostra il logo della tua azienda nella schermata per il consenso. Utilizza le linee guida di stile per posizionare il logo. Se vuoi mostrare anche il logo di Google, consulta Loghi e marchi.

Questa figura mostra un esempio di schermata di consenso con callout per i singoli requisiti e consigli da seguire quando progetti una schermata di consenso dell'utente.
Figura 1: linee guida per la progettazione della schermata di consenso per il collegamento dell'account.

Configurazione per App Flip basato su OAuth

Le sezioni seguenti descrivono i prerequisiti per App Flip basato su OAuth e come configurare il progetto App Flip nella Google Home Developer Console.

Crea un'integrazione cloud-to-cloud e configura un server OAuth 2.0

Prima di poter configurare App Flip, devi:

Configura App Flip nella Console per sviluppatori

La sezione seguente descrive come configurare App Flip nella Console per gli sviluppatori.

  1. Compila tutti i campi obbligatori(*) nella sezione Collegamento dell'account. Se App Flip non è supportato, viene utilizzato OAuth standard come metodo di riserva.
  2. Fornisci un URL per URL di fulfillment cloud. L'URL di fulfillment cloud viene utilizzato per elaborare gli intent di smart home. Seleziona Fulfillment locale.
  3. In App Flip (facoltativo), seleziona App per Android.
  4. Compila i seguenti campi:
    • ID applicazione. L'ID applicazione è un ID univoco che imposti per la tua app.
    • Firma dell'app. Le app per Android devono essere "firmate" con un certificato di chiave pubblica prima di poter essere installate. Per informazioni su come ottenere la firma dell'app, consulta Autenticazione del client.
    • Intent di autorizzazione. In questo campo, inserisci una stringa che specifica l'azione dell'intent.
  5. Se vuoi configurare il client, aggiungi gli ambiti e fai clic su Aggiungi ambito in Ambiti (facoltativo).
  6. Se il tuo client lo richiede, seleziona Consenti a Google di trasmettere l'ID client e il secret tramite l'intestazione di autenticazione di base HTTP.

Ora puoi passare alla sezione successiva per implementare App Flip nella tua app Android.

Implementa App Flip nelle tue app native

Per implementare App Flip, devi modificare il codice di autorizzazione utente nella tua app in modo che accetti un deep link da Google.

Il collegamento App Flip basato su OAuth (App Flip) inserisce la tua app per Android nel flusso di collegamento dell'Account Google. Un flusso di collegamento degli account tradizionale richiede all'utente di inserire le proprie credenziali nel browser. L'utilizzo di App Flip rimanda l'accesso dell'utente alla tua app per Android, consentendoti di sfruttare le autorizzazioni esistenti. Se l'utente ha eseguito l'accesso alla tua app, non deve reinserire le proprie credenziali per collegare l'account. Per implementare App Flip nella tua app per Android, sono necessarie modifiche minime al codice.

In questo documento scoprirai come modificare la tua app per Android per supportare App Flip.

Prova l'esempio

L'app di esempio di collegamento App Flip mostra un'integrazione del collegamento dell'account compatibile con App Flip su Android. Puoi utilizzare questa app per verificare come rispondere a un intent App Flip in arrivo dalle app mobile Google.

L'app di esempio è preconfigurata per l'integrazione con lo strumento di test di App Flip per Android, che puoi utilizzare per verificare l'integrazione della tua app per Android con App Flip prima di configurare il collegamento dell'account con Google. Questa app simula l'intent attivato dalle app mobile Google quando App Flip è abilitato.

Come funziona

Per eseguire un'integrazione di App Flip, sono necessari i seguenti passaggi:

  1. L'app Google verifica se la tua app è installata sul dispositivo utilizzando il suo nome di pacchetto.
  2. L'app Google utilizza un controllo della firma del pacchetto per verificare che l'app installata sia quella corretta.
  3. L'app Google crea un intent per avviare un'attività designata nella tua app. Questo intent include dati aggiuntivi necessari per il collegamento. Inoltre, verifica se la tua app supporta App Flip risolvendo questo intent tramite il framework Android.
  4. La tua app convalida che la richiesta provenga dall'app Google. Per farlo, controlla la firma del pacchetto e l'ID client fornito.
  5. La tua app richiede un codice di autorizzazione al tuo server OAuth 2.0. Al termine di questo flusso, restituisce un codice di autorizzazione o un errore all'app Google.
  6. L'app Google recupera il risultato e continua con il collegamento dell'account. Se viene fornito un codice di autorizzazione, lo scambio di token avviene da server a server, nello stesso modo in cui avviene nel flusso di collegamento OAuth basato su browser.

Modifica l'app per Android per supportare App Flip

Per supportare App Flip, apporta le seguenti modifiche al codice della tua app per Android:

  1. Aggiungi un <intent-filter> al file AndroidManifest.xml con una stringa di azione corrispondente al valore inserito nel campo Intent App Flip.

    <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. Convalida la firma dell'app di chiamate.

    Devi far corrispondere il nome e la firma del pacchetto per tutte le app Google che gli utenti potrebbero utilizzare per il collegamento dell'account. Ad esempio, per eseguire il collegamento alle app Google Home e Ricerca, aggiungi i nomi e le firme dei relativi pacchetti:

    • Nome pacchetto: com.google.android.apps.chromecast.app
    • Certificato di derivazione SHA-256 originale: 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
    • Certificato SHA-256 della firma dell'app di Google Play ruotato: 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

    e

    • Nome pacchetto: com.google.android.googlequicksearchbox
    • Firma: 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

    Le richieste di collegamento della smart home vengono avviate direttamente da Google Home app (GHA). Se la tua applicazione limita i chiamanti e in precedenza consentiva solo l'app Ricerca Google, devi aggiungere com.google.android.apps.chromecast.app e i relativi certificati SHA-256 alla tua lista consentita affinché App Flip continui a funzionare.

    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. Estrai l'ID client dai parametri dell'intent e verifica che l'ID client corrisponda al valore previsto.

    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. In caso di autorizzazione riuscita, restituisci il codice di autorizzazione risultante a Google.

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

  5. Se si è verificato un errore, restituisci un risultato di errore.

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

Contenuto dell'intent di lancio

L'intent Android che avvia la tua app include i seguenti campi:

  • CLIENT_ID (String): Google client_id registrato nella tua app.
  • SCOPE (String[]): un elenco di ambiti richiesti.
  • REDIRECT_URI (String): l'URL di reindirizzamento.

Contenuto dei dati della risposta

I dati restituiti all'app Google vengono impostati nella tua app chiamando setResult(). Questi dati includono:

  • AUTHORIZATION_CODE (String): il valore del codice di autorizzazione.
  • resultCode (int): comunica l'esito positivo o negativo del processo e assume uno dei seguenti valori:
    • Activity.RESULT_OK: indica che l'operazione è andata a buon fine; viene restituito un codice di autorizzazione.
    • Activity.RESULT_CANCELLED: un errore recuperabile. Segnala che l'utente ha annullato la procedura. In questo caso, l'app Google tenterà di nuovo il collegamento dell'account utilizzando l'URL di autorizzazione.
    • -2: indica che si è verificato un errore. Di seguito sono descritti i diversi tipi di errori.
  • ERROR_TYPE (int): il tipo di errore, che assume uno dei seguenti valori:
    • 1: errore recuperabile. L'app Google tenterà di collegare l'account utilizzando l'URL di autorizzazione.
    • 2: errore irreversibile. L'app Google interrompe il collegamento dell'account.
    • 3: parametri della richiesta non validi o mancanti.
  • ERROR_CODE (int): un numero intero che rappresenta la natura dell'errore. Per scoprire il significato di ogni codice di errore, consulta la tabella dei codici di errore.

  • ERROR_DESCRIPTION (String, facoltativo): messaggio di stato leggibile che descrive l'errore.

È previsto un valore per AUTHORIZATION_CODE quando resultCode == Activity.RESULT_OK. In tutti gli altri casi, il valore di AUTHORIZATION_CODE deve essere vuoto. Se resultCode == -2, il valore ERROR_TYPE deve essere compilato.

Tabella dei codici di errore

La tabella seguente mostra i diversi codici di errore e se si tratta di un errore recuperabile o non recuperabile:

Codice di errore Significato Recuperabile Non recuperabile
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 ✔

Per tutti i codici di errore, devi restituire il risultato dell'errore tramite setResult per assicurarti che venga attivato il comportamento di riserva appropriato.

Testa App Flip sul tuo dispositivo

Ora che hai creato un'integrazione cloud-to-cloud e configurato App Flip nella console e nella tua app, puoi testare App Flip sul tuo dispositivo mobile. Puoi utilizzare l'app Google Home per testare App Flip.

Per testare App Flip dall'app Google Home, segui questi passaggi:

  1. Vai alla Console per gli sviluppatori e seleziona il tuo progetto.
  2. Vai a Cloud-to-cloud > Test.
  3. Attiva il flusso di collegamento degli account dall'app Home:
    1. Apri l'app Google Home app (GHA).
    2. Fai clic sul pulsante +.
    3. Fai clic su Configura dispositivo.
    4. Fai clic su Hai già configurato qualcosa?
    5. Seleziona la tua integrazione cloud-to-cloud dall'elenco dei fornitori. Il nome sarà preceduto da "[test]" nell'elenco. Quando selezioni l'integrazione [test] dall'elenco, dovrebbe aprirsi l'app.
    6. Verifica che l'app sia stata avviata e inizia a testare il flusso di autorizzazione.
Indietro
Creare un'integrazione cloud-to-cloud
Avanti
iOS