Google sta eseguendo la transizione del collegamento degli account per la smart home di terze parti in modo che venga gestito completamente e indipendentemente all'interno dell'app Google Home. Potrebbe essere necessario aggiornare l'integrazione prima del 30 ottobre 2026. Per saperne di più, consulta la guida alla migrazione del collegamento degli account.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

App Flip per iOS

Una volta implementato OAuth 2.0, puoi facoltativamente configurare il App Flip basato su OAuth, che consente agli utenti iOS 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 iOS.

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

Devi avere una dichiarazione di autorizzazione di Google, ad esempio "Una volta collegato, Google avrà l'autorizzazione per controllare i tuoi dispositivi".
Devi comunicare che l'account dell'utente viene collegato a Google, non a un prodotto Google specifico, come Google Home o l'Assistente Google.
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.
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.
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:

Visualizza le Norme sulla privacy di Google. Includi un link alle Norme sulla privacy di Google nella schermata per il consenso.
Dati da condividere. Utilizza un linguaggio chiaro e conciso per comunicare all'utente quali dati di sua proprietà sono richiesti da Google e perché.
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.
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.
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 un server OAuth 2.0. Per saperne di più sulla configurazione di un server OAuth, consulta Implementa un server OAuth 2.0.
Crea un'integrazione cloud-to-cloud. Per creare un'integrazione, segui le istruzioni riportate in Crea un'integrazione cloud-to-cloud.

Configura App Flip nella Console per sviluppatori

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

Compila tutti i campi in Informazioni client OAuth. (Se App Flip non è supportato, viene utilizzato OAuth standard come riserva).
In Utilizza la tua app per il collegamento degli account(facoltativo), seleziona Attiva per iOS.
Compila il campo Link universale. Per ulteriori informazioni sui link universali, consulta Consentire ad app e siti web di collegarsi ai tuoi contenuti.
Se vuoi configurare il client, aggiungi gli ambiti e fai clic su Aggiungi ambito in Configura il client (facoltativo).
Fai clic su Salva.

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

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) apre la tua app per iOS da un'app Google per aiutare l'utente dell'app Google a collegare più facilmente il proprio account. Per implementare questa funzionalità, devi apportare piccole modifiche al codice della tua app per iOS.

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

Prova l'esempio

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

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

Come funziona

Di seguito sono riportati i passaggi del flusso eseguiti dall'app Google e dalla tua app quando si verifica App Flip:

L'app Google tenta di aprire il link universale della tua app. È in grado di aprire la tua app se è installata sul dispositivo dell'utente e associata al link universale. Per informazioni dettagliate, consulta Supporto dei link universali.
La tua app verifica che i parametri client_id e redirect_uri codificati nell'URL in entrata corrispondano al link universale di Google previsto.
La tua app richiede un codice di autorizzazione al tuo server OAuth2. Al termine di questo flusso, l'app restituisce un codice di autorizzazione o un errore all'app Google. Per farlo, apre il link universale di Google con i parametri aggiunti per il codice di autorizzazione o l'errore.
L'app Google gestisce il link universale di Google in entrata e continua con il resto del flusso. Se viene fornito un codice di autorizzazione, il collegamento viene completato immediatamente. Lo scambio di token avviene server-to-server, nello stesso modo in cui avviene nel flusso di collegamento OAuth basato su browser. Se viene restituito un codice di errore, il flusso di collegamento continua con le opzioni alternative.

Modifica l'app per iOS per supportare App Flip

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

Gestisci NSUserActivityTypeBrowsingWeb nel tuo App Delegate.
Acquisisci i parametri redirect_uri e state dall'URL per utilizzarli in un secondo momento.

Verifica che redirect_uri corrisponda a questo formato:

https://oauth-redirect.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID
https://oauth-redirect-sandbox.googleusercontent.com/a/GOOGLE_APP_BUNDLE_ID

Verifica che l'ID client corrisponda al valore previsto. Utilizza il seguente esempio di codice:

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool
{
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = URLComponents(url: incomingURL, resolvingAgainstBaseURL: false),
        let params = components.queryItems else {
            return false
    }

    if let clientId = params.filter({$0.name == "client_id"}).first?.value,
        let state = params.filter({$0.name == "state"}).first?.value,
        let redirectUri = params.filter({$0.name == "redirect_uri"}).first?.value {

        // Save the redirect_uri and state for later...

        // Verify the client id
        return (clientId == GOOGLE_CLIENT_ID)
    } else {
        // Missing required parameters
        return false
    }
}

In caso di autorizzazione riuscita, chiama l'URI di reindirizzamento con il codice di autorizzazione. Utilizza il seguente esempio di codice:

func returnAuthCode(code: String, state: String, redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramAuthCode = URLQueryItem(name: "code", value: code)
    let paramState = URLQueryItem(name: "state", value: state)
    components?.queryItems = [paramAuthCode, paramState]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Se si è verificato un errore, allega un risultato di errore all'URI di reindirizzamento. Utilizza il seguente esempio di codice:

func returnError(redirectUri: String) {
    var redirectURL = URL(string: redirectUri)
    var components = URLComponents(url: redirectURL, resolvingAgainstBaseURL: false)

    // Return the authorization code and original state
    let paramError = URLQueryItem(name: "error", value: "invalid_request")
    let paramDescription = URLQueryItem(name: "error_description", value: "Invalid Request")
    components?.queryItems = [paramError, paramDescription]
    if let resultURL = components?.url {
        UIApplication.shared.open(
            resultURL,
            options: [UIApplicationOpenURLOptionUniversalLinksOnly : true],
            completionHandler: nil)
    }
}

Parametri di query per il link universale della tua app

Quando viene aperto dall'app Google, il link universale della tua app include i seguenti parametri di query:

client_id (String): client_id Google registrato nella tua app.
scope (List of String): un elenco di ambiti richiesti separati da spazi.
state (String): un nonce utilizzato da Google per verificare che il risultato dell'autorizzazione sia in risposta alla richiesta in uscita di Google.
redirect_uri (String): link universale di Google. L'URI "flip" per aprire l'app Google e passare i risultati.

Parametri di query per il link universale di Google

Parametri utilizzati quando il risultato dell'autorizzazione viene restituito correttamente:

code (String): il valore del codice di autorizzazione, se disponibile.
state (String): il valore esatto ricevuto dal link universale in entrata.

Parametri utilizzati quando il risultato dell'autorizzazione non viene restituito correttamente:

error (String), con i seguenti valori:
- cancelled: un errore recuperabile. L'app Google tenterà di collegare l'account utilizzando l'URL di autorizzazione. Alcuni esempi sono l'impossibilità di accedere da parte dell'utente, un dispositivo offline o il timeout di una connessione.
- unrecoverable: un errore irreversibile. Ad esempio, l'utente tenta di collegare un account disattivato.L'app Google interromperà il collegamento dell'account.
- invalid_request: i parametri della richiesta non sono validi o sono mancanti. Questo è un errore recuperabile. L'app Google tenterà di collegare l'account utilizzando l'URL di autorizzazione.
- access_denied: l'utente rifiuta la richiesta di consenso. Si tratta di un errore non recuperabile; l'app Google interrompe il collegamento.
error_description (String, facoltativo): un messaggio di errore facile da usare.

Nota: per saperne di più sui possibili errori e sui contenuti facoltativi del campo error_description, consulta lo standard OAuth 2.0.

Per tutti i tipi di errore, devi restituire i dati della risposta al REDIRECT_URI specificato per assicurarti che venga attivato il fallback appropriato.

Modifica l'endpoint di autorizzazione per supportare App Flip

Configura la tua piattaforma in modo che accetti le richieste utilizzando gli URL di reindirizzamento di App Flip di Google:

App Google Home

https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.Chromecast
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.Chromecast

App Assistente Google

https://oauth-redirect.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect.googleusercontent.com/a/com.google.OPA
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.dev
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA.enterprise
https://oauth-redirect-sandbox.googleusercontent.com/a/com.google.OPA

Per Google Home app (GHA), il collegamento dell'account per la smart home utilizza gli URL di reindirizzamento com.google.Chromecast. Assicurati che il tuo server di autorizzazione consenta questi URL di reindirizzamento.

Verifica che client_id e l'URL specificato dal parametro redirect_uri corrispondano ai valori previsti quando viene ricevuta una richiesta. Se la verifica del client non va a buon fine, restituisci l'errore invalid_request a redirect_uri.

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:

Vai alla Console per gli sviluppatori e seleziona il tuo progetto.
Vai a Cloud-to-cloud > Test.
Attiva il flusso di collegamento degli account dall'app Home:

Apri l'app Google Home app (GHA).
Fai clic sul pulsante +.
Fai clic su Configura dispositivo.
Fai clic su Hai già configurato qualcosa?
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.
Verifica che l'app sia stata avviata e inizia a testare il flusso di autorizzazione.

Indietro

Android

Avanti

Identifica e sincronizza