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. Con l'API Permissions, l'utente può, utilizzando il proprio Account Google, concedere alle app API Home l'accesso ai dispositivi di casa sua.

Integrare l'API Permissions

Prima di continuare, assicurati di aver seguito la procedura per inizializzare la casa. 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 Google Home 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.

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.

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.