API Permissions

Prima di utilizzare una delle API Home, l'app deve disporre dell'autorizzazione per accedere ai dispositivi nella casa dell'utente, denominata nell'API la struttura.

Le API Home utilizzano OAuth 2.0 per concedere l'accesso ai dispositivi della struttura. OAuth consente a un utente di concedere l'autorizzazione a un'app o a un servizio senza dover divulgare le proprie credenziali di accesso. Con l'API Permissions, l'utente può, utilizzando il proprio Account Google, concedere alle app API Home l'accesso ai dispositivi di casa sua.

L'utilizzo dell'API Permissions prevede una serie di passaggi nell'app, in Google Cloud e nel Google Home Developer Console:

1. Configurare OAuth in Google Cloud
   1. Firmare l'app
   2. Configura la schermata per il consenso OAuth
   3. Registra l'app e crea le credenziali
2. Integra l'API Permissions
   1. Verificare le autorizzazioni
   2. Richiedi autorizzazioni
3. Concedere le autorizzazioni
   1. Modifica autorizzazioni
   2. Revocare le autorizzazioni

Configurare OAuth in Google Cloud

Se hai già un client OAuth verificato, puoi utilizzarlo senza doverne configurare uno nuovo. Per ulteriori informazioni, consulta Se hai già un client OAuth.

Firmare l'app

1. Genera una chiave OAuth eseguendo l'app in Android Studio. Quando esegui o esegui il debug di un'app in Android Studio, viene generata automaticamente una chiave OAuth destinata allo sviluppo e al debug. Per una spiegazione completa, consulta Android Studio: firma la build di debug.

   Collega il dispositivo mobile al computer locale. Android Studio elenca i tuoi dispositivi connessi in base al numero di modello. Seleziona il tuo dispositivo dall'elenco, quindi fai clic su Esegui progetto. L'app di esempio viene compilata e installata sul tuo dispositivo mobile.

   Per istruzioni più dettagliate, consulta Eseguire app su un dispositivo hardware sul sito Android for Developers.

   Ora interrompi l'app in esecuzione.

2. Ottieni la fingerprint SHA-1 del certificato OAuth seguendo le istruzioni dettagliate in Configurazione di OAuth 2.0 / App native/Android sul sito di assistenza della console Google Cloud.

Configura la schermata per il consenso OAuth

1. Nella console Google Cloud, vai alla dashboard del selettore di progetti e seleziona il progetto che vuoi utilizzare per creare le credenziali OAuth.
2. Vai alla pagina API e servizi e fai clic su Credenziali nel menu di navigazione.

3. Se non hai ancora configurato la schermata del consenso per questo progetto Google Cloud, viene visualizzato il pulsante Configura schermata del consenso. In questo caso, configura la schermata del consenso utilizzando la procedura riportata di seguito. In caso contrario, vai alla sezione successiva.

   1. Fai clic su Configura schermata di consenso. Viene visualizzata la pagina della schermata per il consenso OAuth.
   2. A seconda del caso d'uso, seleziona Interno o Esterno e fai clic su Crea. Viene visualizzato il riquadro Schermata per il consenso OAuth.
   3. Inserisci le informazioni nella pagina Informazioni sull'app seguendo le istruzioni sullo schermo e poi fai clic su Salva e continua. Viene visualizzato il riquadro Ampi dello spettro.
   4. Non devi aggiungere ambiti, quindi fai clic su Salva e continua. Viene visualizzato il riquadro Utenti di test.
   5. Se vuoi aggiungere utenti per testare l'accesso alla tua app, fai clic su Aggiungi utenti. Viene visualizzato il riquadro Aggiungi utenti. Gli utenti di test hanno il privilegio di concedere le autorizzazioni nella tua app.
   6. Nel campo vuoto, aggiungi uno o più indirizzi email dell'Account Google, poi fai clic su Aggiungi.
   7. Fai clic su Salva e continua. Viene visualizzato il riquadro Riepilogo.
   8. Rivedi le informazioni della schermata per il consenso OAuth, quindi fai clic su Torna alla dashboard.

Per informazioni dettagliate, consulta la sezione Configurare la schermata per il consenso OAuth sul sito di assistenza della console Google Cloud.

Registra l'app e crea le credenziali

Per registrare l'app per OAuth 2.0 e creare le credenziali OAuth, segui le istruzioni fornite in Configurare OAuth 2.0. Dovrai indicare il tipo di app, ovvero app nativa/Android.

Aggiungi l'impronta SHA-1 ottenuta dalla firma dell'app al client OAuth configurato nella console Google Cloud seguendo le istruzioni riportate in Configurazione di OAuth 2.0 / app native sul sito di assistenza della console Google Cloud.

Con il dispositivo mobile connesso alla macchina locale, selezionalo dall'elenco, quindi fai di nuovo clic su Esegui progetto per eseguirlo. Per istruzioni più dettagliate, consulta Eseguire app su un dispositivo hardware sul sito Android for Developers.

Integrare l'API Permissions

Gli utenti devono concedere autorizzazioni alla tua app per accedere ai dispositivi all'interno di una determinata struttura. Per iniziare, assicurati di aver inizializzato le API di Home. L'istanza homeManager di quel passaggio viene utilizzata in tutti gli esempi di autorizzazioni riportati di seguito.

Innanzitutto, registra un ActivityResultCaller con l'SDK. Ad esempio, l'app di esempio gestisce la situazione nel seguente modo:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Verificare le autorizzazioni

Prima di richiedere le autorizzazioni, ti consigliamo di verificare se l'utente dell'app ha già concesso il consenso. A questo scopo, chiama il metodo hasPermissions() dell'istanza Home per ottenere un Flow di PermissionsState valori:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Se il controllo restituisce un PermissionsState di NOT_GRANTED o PERMISSIONS_STATE_UNAVAILABLE, devi richiedere le autorizzazioni. Se il controllo restituisce un PermissionsState di GRANTED, ma una chiamata successiva a structures() non restituisce strutture, l'utente ha revocato l'accesso all'app tramite la pagina delle impostazioni di Google Home app (GHA) e devi richiedere le autorizzazioni. In caso contrario, l'utente dovrebbe già disporre dell'accesso.

Richiedi autorizzazioni

L'autorizzazione deve essere concessa alla tua app per accedere alle strutture e ai dispositivi all'interno di una determinata struttura.

Se l'utente non ha già concesso le autorizzazioni, utilizza il metodo requestPermissions() dell'istanza Home per avviare l'interfaccia utente delle autorizzazioni ed elaborare il risultato:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

Affinché l'interfaccia utente delle autorizzazioni venga lanciata correttamente, devi aver già configurato OAuth per la tua app.

Concedi le autorizzazioni

Ora dovresti essere in grado di eseguire l'app e di avere un utente che concede le autorizzazioni. Il tipo di utenti che possono concedere l'autorizzazione e i tipi di dispositivi per i quali è possibile concedere le autorizzazioni variano a seconda che tu abbia registrato la tua app in Developer Console.

La registrazione a Developer Console è obbligatoria per pubblicare un'app che utilizza le API di Home. Non è necessario testare e utilizzare le API Home. Per accedere alla funzionalità di registrazione della console, contatta il tuo account GoogleTechnical Account Manager (TAM).

Se un'app non è registrata in Developer Console, sarà in stato non verificato. Questa opzione è consigliata per testare l'utilizzo delle API Home:

• Solo gli utenti registrati come utenti di test nella console OAuth possono concedere le autorizzazioni per l'app. Esiste un limite di 100 utenti di test per un'app non verificata.

• Un'app non verificata avrà accesso ai dispositivi di qualsiasi tipo supportati da OAuth per le API Home (l'elenco dei tipi di dispositivi in Developer Console). Verranno concessi tutti i dispositivi di una struttura.

Se un'app è registrata in Developer Console e è stata approvata per l'accesso a uno o più tipi di dispositivi e la verifica del brand è stata completata per OAuth, sarà in stato Verificato. Questo stato è necessario per il lancio di un'app in produzione:

• I limiti di utenti di prova non vengono più applicati. Qualsiasi utente può concedere l'autorizzazione all'app.
• L'utente può concedere l'autorizzazione solo ai tipi di dispositivi approvati nel Developer Console.

Ora che OAuth è configurato, la chiamata dell'app a requestPermissions() attiva le seguenti finestre di dialogo:

1. All'utente viene chiesto di selezionare l'Account Google che vuole utilizzare.
2. All'utente viene chiesto di selezionare la struttura a cui vuole concedere l'accesso all'app.
   1. Per un'app non verificata, sono disponibili tutti i tipi di dispositivi supportati dalle API Home.
   2. Per un'app verificata, l'utente può concedere l'autorizzazione solo ai tipi di dispositivi che sono stati approvati in Developer Console.
   3. Per i tipi di dispositivi sensibili di cui l'app ha accesso in gestione, l'utente può limitare l'accesso in base al dispositivo. Ad esempio, se un utente ha tre serrature, può concedere l'accesso a una sola di queste.

Una volta concessa l'autorizzazione, l'app può utilizzare le API Home per leggere lo stato e controllare i dispositivi della struttura. Se l'utente non concede all'app l'autorizzazione per un determinato tipo di dispositivo o un dispositivo sensibile, l'app non potrà utilizzare le API Home per accedervi, controllarlo o automatizzarlo.

Modifica autorizzazioni

Per concedere l'autorizzazione di accesso ai dispositivi di un'altra struttura, è possibile avviare il selettore di account per consentire all'utente di scegliere l'Account Google e la struttura a cui passare. Durante questa procedura, all'utente verrà mostrata di nuovo la schermata per il consenso, anche se il consenso è stato concesso in precedenza.

Per farlo, chiama di nuovo requestPermissions() con il flag forceLaunch impostato su true:

homeManager.requestPermissions(forceLaunch=true)

Revocare le autorizzazioni

Gli utenti possono revocare l'accesso concesso in precedenza:

1. Dalla pagina Google MyAccounts > Dati e privacy > Servizi e app di terze parti. In questo modo, verrà revocato il token OAuth emesso al momento della concessione del consenso iniziale e l'accesso a qualsiasi istanza dell'app in uso dall'utente su tutte le piattaforme (smartphone) e strutture.

2. Tramite la pagina GHA > Impostazioni > App collegate. Se fai clic su settings in GHA, viene visualizzata la pagina Impostazioni. Da qui, fai clic sul riquadro App collegate per aprire una pagina simile alla schermata del consenso. Da questa pagina l'utente può rimuovere l'accesso all'app. L'utente può utilizzare la stessa pagina per modificare i tipi di dispositivi o dispositivi sensibili specifici accessibili all'app.

3. Tramite la pagina App collegate direttamente sul web.

Se hai già un client OAuth

Se hai già un client OAuth verificato per un'app pubblicata, puoi utilizzare il client OAuth esistente per testare le API Home.

La registrazione a Developer Console non è necessaria per testare e utilizzare le API Home. Tuttavia, per pubblicare l'app dovrai comunque disporre di una registrazioneDeveloper Console approvata, anche se hai un client OAuth verificato di un'altra integrazione.

Si applicano le seguenti considerazioni:

• Esiste un limite di 100 utenti quando si utilizza un client OAuth esistente. Per informazioni sull'aggiunta di utenti di test, consulta Configurare la schermata di consenso OAuth. Indipendentemente dalla verifica OAuth, esiste un limite imposto dalle API Home di 100 utenti che possono concedere autorizzazioni alla tua applicazione. Questa limitazione viene rimossa al termine della registrazione a Developer Console.

• LaDeveloper Console deve essere inviata per l'approvazione quando è tutto pronto per limitare le concessioni per tipo di dispositivo tramite OAuth in vista dell'aggiornamento dell'app con le API Home.

Per le app Google Cloud per le quali la verifica OAuth è ancora in attesa, gli utenti non possono completare il flusso OAuth finché la verifica non è completata. I tentativi di concessione delle autorizzazioni non andranno a buon fine con il seguente errore:

Access blocked: <Project Name> has not completed the Google verification process.

Autorizzazioni OkGoogle

Il comando okGoogle è un comando a livello di struttura e può essere utilizzato per automatizzare qualsiasi dispositivo all'interno della struttura. Tuttavia, un'app API Home potrebbe non avere accesso a tutti i dispositivi. La tabella seguente descrive come vengono applicate le autorizzazioni in questi casi.