App Flip per Android

Una volta implementata un'implementazione di OAuth 2.0, puoi configurare App Flip in base a OAuth; questo consente agli utenti di Android di collegare più rapidamente gli account del tuo sistema di autenticazione agli account Google. Le seguenti sezioni descrivono come progettare e implementare App Flip per l'azione smart home.

Istruzioni sul design

Questa sezione descrive i requisiti e i consigli di progettazione per la schermata per il consenso in merito al collegamento dell'account App Flip. Dopo aver chiamato l'app, l'app mostra la schermata di consenso all'utente.

Requisiti

  1. Devi comunicare che l'account dell'utente è collegato a Google, non a un prodotto Google specifico, come Google Home o Assistente Google.

Suggerimenti

Ti consigliamo di procedere come segue:

  1. Mostra 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 spiegare all'utente i dati relativi a Google richiesti e il motivo.

  3. Invito all'azione chiaro. Nella schermata di consenso, indica un chiaro invito all'azione, ad esempio "Accetta e collega". perché gli utenti devono capire quali dati devono condividere con Google per collegare i loro account.

  4. Possibilità di annullare. Fornisci un modo per gli utenti di tornare indietro o annullare, se scelgono di non collegare.

  5. Possibilità di scollegamento. Offri agli utenti un meccanismo di scollegamento, ad esempio un URL alle impostazioni account sulla tua piattaforma. In alternativa, puoi includere un link a un Account Google da cui gli utenti possono gestire il proprio account collegato.

  6. Possibilità di cambiare account utente. Suggerisci un metodo che consenta agli utenti di cambiare account. Ciò è particolarmente utile se gli utenti tendono ad avere più account.

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

  7. Includi il tuo logo. Mostra il logo della tua azienda nella schermata per il consenso. Utilizza le tue linee guida relative allo stile per inserire il logo. Se vuoi visualizzare anche il logo di Google, consulta Loghi e marchi.

Questa figura mostra una schermata di consenso di esempio con callout ai singoli requisiti e consigli da seguire durante la progettazione di una schermata per il consenso degli utenti.
Figura 1: linee guida per la progettazione della schermata di consenso per il collegamento dell'account.

Configurare il Flip per app basato su OAuth

Le seguenti sezioni descrivono i prerequisiti per App Flip basato su OAuth e come configurare il tuo progetto App Flip nella console Actions.

Crea un'azione per la smart home e configura un server OAuth 2.0

Prima di configurare App Flip, devi eseguire le seguenti operazioni:

Configurare App Flip nella console Actions

La sezione seguente descrive come configurare App Flip nella console di Actions.

  1. Compila tutti i campi nella sezione Informazioni sul client OAuth. Se App Flip non è supportato, viene utilizzato il protocollo OAuth di riserva.
  2. In Utilizza la tua app per il collegamento dell'account (facoltativo), seleziona Abilita per Android.
  3. Compila i seguenti campi:
    • ID applicazione. L'ID applicazione è un ID univoco impostato per la tua app.
    • Firma dell'app. Per poter essere installate, le app per Android devono essere "firmate" con un certificato di chiave pubblica. Per informazioni su come ottenere la firma della tua app, consulta l'articolo su come autenticare il client.
    • Intent di autorizzazione. In questo campo, inserisci una stringa che specifichi l'azione.
  4. (Facoltativo) Se vuoi configurare il client, aggiungi ambiti e fai clic su Aggiungi ambito in Configura il client (facoltativo).
  5. Fai clic su Salva.

Implementa App Flip nelle tue app per Android

Per implementare App Flip, devi modificare il codice di autorizzazione dell'utente nell'app per accettare un link diretto da Google.

Il collegamento di app Flip basato su OAuth (App Flip) inserisce la tua app Android nel flusso di collegamento dell'Account Google. Un flusso di collegamento dell'account tradizionale richiede all'utente di inserire le proprie credenziali nel browser. L'uso di App Flip posticipa l'accesso all'app Android, che ti consente di usare le autorizzazioni esistenti. Se l'utente ha eseguito l'accesso all'app, non deve reinserire le credenziali per collegare il suo account. È richiesta una quantità minima di modifiche al codice per implementare App Flip sulla tua app Android.

Questo documento spiega come modificare l'app Android per supportare App Flip.

Prova l'anteprima

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

L'app di esempio è preconfigurata per l'integrazione con lo Strumento di test delle app Android, che puoi utilizzare per verificare l'integrazione della tua app Android con Flip prima di configurare il collegamento dell'account a Google. Questa app simula l'intent attivato dalle app per dispositivi mobili Google quando è attiva l'opzione App Flip.

Come funziona

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

  1. L'app Google controlla se la tua app è installata sul dispositivo utilizzando il suo nome del pacchetto.
  2. L'app Google utilizza un controllo della firma del pacchetto per verificare che sia app 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, controlla se la tua app supporta App Flip risolvendo questo scopo tramite il framework Android.
  4. L'app convalida che la richiesta proviene 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 server-server, allo stesso modo del flusso di collegamento OAuth basato sul browser.

Modificare l'app Android per supportare App Flip

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

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

    <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. Convalidare la firma dell'app per le chiamate.

    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. 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 = "<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. Se l'autorizzazione è andata a buon fine, 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, restituisce un risultato.

    // 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'intenzione di lancio

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

  • CLIENT_ID (String): dominio Google client_id registrato nella tua app.
  • SCOPE (String[]): elenco di ambiti richiesto.
  • 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 quanto segue:

  • AUTHORIZATION_CODE (String): il valore del codice di autorizzazione.
  • resultCode (int): comunica la riuscita o la mancata riuscita del processo e adotta uno dei seguenti valori:
    • Activity.RESULT_OK: indica che l'operazione è riuscita. Viene restituito un codice di autorizzazione.
    • Activity.RESULT_CANCELLED: indica che l'utente ha annullato la procedura. In questo caso, l'app Google tenterà di collegare l'account utilizzando il tuo URL di autorizzazione.
    • -2: indica che si è verificato un errore. Di seguito sono descritti diversi tipi di errori.
  • ERROR_TYPE (int): il tipo di errore, che utilizza 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 degli account.
    • 3: parametri della richiesta non validi o mancanti.
  • ERROR_CODE (int): un numero intero che rappresenta la natura dell'errore. Per sapere cosa significa ogni codice di errore, consulta la tabella dei codici di errore.

  • ERROR_DESCRIPTION (String, facoltativo): messaggio di stato leggibile da cui viene descritto 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 dovrebbe essere completato.

Tabella dei codici di errore

La tabella seguente mostra i diversi codici di errore e indica 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 a livello di errore tramite setResult per assicurarti che venga attivato l'elemento di riserva appropriato.

Testa l'app Flip sul tuo dispositivo

Ora che hai creato un'azione e configurato App Flip sulla console e nella tua app, puoi testare App Flip sul tuo dispositivo mobile. Puoi utilizzare l'app Assistente Google o l'app Google Home per testare l'app Flip.

Per testare App Flip dall'app Assistente, procedi nel seguente modo:

  1. Vai alla console di Actions e seleziona il tuo progetto.
  2. Fai clic su Prova nella barra di navigazione in alto.
  3. Attivare il flusso di collegamento dell'account dall'app Assistente:
    1. Apri l'app Assistente Google.
    2. Fai clic su Impostazioni.
    3. Nella scheda Assistente Google, fai clic su Controllo della casa.
    4. Fai clic su Aggiungi(+).
    5. Seleziona l'azione dall'elenco dei provider. Nell'elenco sarà presente il prefisso "[test]". Quando selezioni l'azione [test] dall'elenco, l'app dovrebbe essere aperta.
    6. Verifica che l'app sia stata avviata e inizia a testare il flusso di autorizzazione.

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

  1. Vai alla console di Actions e seleziona il tuo progetto.
  2. Fai clic su Prova nella barra di navigazione in alto.
  3. Attiva il flusso di collegamento dell'account dall'app Home:
    1. Apri l'app Google Home.
    2. Fai clic sul pulsante +.
    3. Fai clic su Configura dispositivo.
    4. Fai clic su Hai già configurato qualcosa?.
    5. Seleziona l'azione relativa alla tua smart home nell'elenco di fornitori. Nell'elenco sarà presente il prefisso "[test]". Quando selezioni l'azione [test] dall'elenco, l'app dovrebbe essere aperta.
    6. Verifica che l'app sia stata avviata e inizia a testare il flusso di autorizzazione.
Indietro
crea un progetto Actions
Avanti
Identifica e sincronizza