API Permissions su Android

Prima di utilizzare una delle API Home per Android, l'app deve disporre dell'autorizzazione per accedere ai dispositivi nella casa dell'utente, indicati nell'API come struttura. Con l'API Permissions, l'utente può, utilizzando il proprio Account Google, concedere alle app API Home l'accesso ai dispositivi della propria casa.

Integra l'API Permissions

Prima di continuare, assicurati di aver seguito la procedura Inizializzare la casa su Android. L'istanza homeManager di questo passaggio viene utilizzata in tutti gli esempi di autorizzazioni riportati di seguito.

Innanzitutto, registra un ActivityResultCaller con l'SDK. Ad esempio, ecco come la gestisce l'app di esempio:

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

Controllare le autorizzazioni

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

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, dovrai 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

Per accedere alle strutture e ai dispositivi all'interno di una determinata struttura, è necessario concedere l'autorizzazione alla tua app.

Se l'utente non ha ancora 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}")
      }
    }
  }
}

Per avviare correttamente l'interfaccia utente delle autorizzazioni, devi aver già configurato OAuth per la tua app.

Concedi le autorizzazioni

Ora dovresti essere in grado di eseguire l'app e fare in modo che un utente conceda le autorizzazioni. Il tipo di utenti che possono concedere l'autorizzazione e i tipi di dispositivi disponibili per concedere le autorizzazioni variano a seconda che tu abbia registrato la tua app in Google Home Developer Console.

Per pubblicare un'app utilizzando le API Home è necessaria la registrazione Developer Console. Non è necessario testare e utilizzare le API Home.

Se un'app non è registrata nel 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 supportato da OAuth per le API per la casa (l'elenco dei tipi di dispositivi è disponibile in Developer Console). Verrà concesso l'accesso a 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, il suo stato sarà verificato. Questo stato è necessario per il lancio di un'app in produzione:

• I limiti per gli utenti di test 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 casa a cui vuole concedere l'accesso all'app.
   1. Per un'app non verificata, tutti i tipi di dispositivi supportati dalle API Home sono disponibili per l'app.
   2. Per un'app verificata, l'utente può concedere l'autorizzazione solo ai tipi di dispositivi approvati in Developer Console.
   3. Per i tipi di dispositivi sensibili che l'app ha accesso a gestire, 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 concesso, l'app può utilizzare le API Home per leggere lo stato e controllare i dispositivi nella struttura. Se l'utente non concede l'autorizzazione all'app per un particolare tipo di dispositivo o dispositivo sensibile, l'app non potrà utilizzare le API Home per accedervi, controllarlo o automatizzarlo.

Modifica autorizzazioni

Per concedere l'autorizzazione ad accedere ai dispositivi in una struttura diversa, è 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)

Revoca delle autorizzazioni

Gli utenti possono revocare l'accesso concesso in precedenza:

1. Tramite la pagina Il mio account Google > Dati e privacy > Servizi e app di terze parti. Verrà revocato il token OAuth emesso al momento della concessione del consenso iniziale e verrà revocato l'accesso a qualsiasi istanza dell'app che l'utente stava utilizzando su tutte le piattaforme (smartphone) e strutture.

   L'utente potrebbe essere indirizzato con un link diretto alla sottopagina App e servizi di terze parti utilizzando il seguente schema URL:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

Autorizzazioni Ok Google

Il comando okGoogle è un comando a livello di dispositivo e può essere utilizzato per automatizzare qualsiasi dispositivo nella 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.