API Permissions su Android

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

Il flusso di autorizzazione consente all'utente di creare una struttura e di assegnare il relativo indirizzo, se non è già stato configurato, senza dover utilizzare Google Home app (GHA).

Integra l'API Permissions

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

Per prima cosa, registra un ActivityResultCaller con l'SDK. Ad esempio, ecco come viene gestito nell'app di esempio:

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

Controlla le autorizzazioni

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

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      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")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

Se il controllo restituisce un PermissionsState di NOT_GRANTED o PERMISSIONS_STATE_UNAVAILABLE, significa che l'utente o l'applicazione non ha accesso alla struttura. Se il controllo restituisce un PermissionsState di GRANTED, ma una chiamata successiva a structures() non restituisce strutture, significa che l'utente ha revocato l'accesso all'app tramite la pagina delle impostazioni di GHA o che l'utente non dispone dell'accesso richiesto.

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 la UI 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 la UI delle autorizzazioni, devi aver già configurato OAuth per la tua app.

La UI di consenso alle autorizzazioni viene visualizzata nelle impostazioni internazionali configurate con HomeClient.setLocale() o, se non impostate, nelle impostazioni internazionali dell'app o del dispositivo. Per visualizzare la schermata per il consenso in una lingua specifica, chiama setLocale() sulla tua istanza HomeClient prima di chiamare requestPermissions(). Per saperne di più, consulta Configura le impostazioni internazionali dell'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 cui concedere le autorizzazioni variano a seconda che tu abbia registrato o meno la tua app in Google Home Developer Console.

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

Se un'app non è registrata in Developer Console, sarà in uno 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). Verrà concesso l'accesso a tutti i dispositivi di una struttura.

Se un'app è registrata in Developer Console ed è stata approvata per l'accesso a uno o più tipi di dispositivi e la verifica del brand è stata completata per OAuth, sarà in stato verificata. Questo stato è obbligatorio 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 struttura 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 può gestire, l'utente può limitare l'accesso in base al dispositivo. Ad esempio, se un utente ha tre serrature, può concedere l'accesso solo a una di queste.

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

Cambia autorizzazioni

Per concedere l'autorizzazione ad accedere ai dispositivi in una struttura diversa, è possibile avviare il selettore dell'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 forcePermissionFlow impostato su ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Modifica le autorizzazioni con i suggerimenti per la struttura

I suggerimenti per la struttura consentono a un'app di preselezionare una struttura specifica o di limitare l'elenco delle strutture disponibili quando richiede una modifica incrementale alle autorizzazioni delle API Home dell'utente. Se passi i parametri della struttura nella richiesta di autorizzazione, la finestra di dialogo delle autorizzazioni si concentrerà automaticamente sulla struttura scelta, riducendo l'attrito dell'utente e prevenendo errori di configurazione.

I suggerimenti per la struttura vengono gestiti utilizzando la classe di dati ConsentScreenOptions. La classe ConsentScreenOptions accetta i seguenti parametri di configurazione:

• structureId: l'ID della struttura specifico da preselezionare nella finestra di dialogo delle autorizzazioni. Puoi ottenerlo controllando le proprietà della struttura per la struttura in fase di aggiornamento.
• allowedStructureIds: un elenco di ID struttura. Se fornito, la finestra di dialogo delle autorizzazioni filtrerà le strutture disponibili per mostrare solo quelle presenti in questo elenco. Nella maggior parte dei casi, questo campo può essere lasciato vuoto, a meno che tu non voglia assicurarti che l'utente rimanga all'interno di un elenco di strutture già concesse.
• allowStructureChange: determina se l'utente è autorizzato a modificare la struttura preselezionata. Imposta questo valore su true se almeno uno tra allowedStructureIds e structureId è specificato nella maggior parte dei casi per supportare il comportamento naturale dell'utente.

Passa questo oggetto come parametro facoltativo nella chiamata requestPermissions(), con forcePermissionFlow impostato su ForcePermissionFlow.FORCE_LAUNCH:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

All'utente verrà mostrata la schermata per il consenso già filtrata in base alla struttura indicata nell'oggetto ConsentScreenOptions.

Consenti all'utente di cambiare struttura con i suggerimenti per la struttura

Se un utente ha più strutture in un'app e vuoi preselezionarne una, consentendogli comunque di passare da una struttura disponibile all'altra, attiva le modifiche alla struttura con il flag allowStructureChange e fornisci un elenco di strutture in allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

Revoca le autorizzazioni

Gli utenti possono revocare l'accesso concesso in precedenza:

1. Tramite le impostazioni dell'Account Google > Dati e privacy > Servizi e app di terze parti. In questo modo, verrà revocato il token OAuth emesso quando è stato concesso il consenso iniziale e verrà revocato l'accesso a qualsiasi istanza dell'app che l'utente stava utilizzando su tutte le piattaforme (smartphone) e le strutture.

   L'utente potrebbe essere indirizzato con un deep link 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 nel GHA, si aprirà la pagina Impostazioni. Da qui, fai clic sul riquadro App collegate, che ti indirizza a una pagina simile alla schermata per il 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.

Eliminazione ed esportazione dei dati utente

La piattaforma gestisce automaticamente l'eliminazione dei dati di backend quando un utente elimina il proprio Account Google o abbandona una struttura:

• Se l'utente eliminato è l'unico proprietario di una struttura, la piattaforma elimina la struttura e le relative associazioni di dispositivi.
• Se altri proprietari rimangono in una struttura condivisa, la struttura e i relativi dispositivi condivisi rimangono per i membri rimanenti. La piattaforma rimuove l'iscrizione dell'utente che ha abbandonato la casa e scollega tutti i dispositivi Cloud-to-cloud di terze parti connessi esclusivamente tramite le credenziali di quell'utente.
• L'eliminazione dell'account rimuove immediatamente e definitivamente i dati della struttura e le autorizzazioni dell'applicazione dell'utente. Anche se l'utente recupera in un secondo momento il proprio Account Google, le sue strutture e le sue autorizzazioni non vengono ripristinate.

Le API Home non forniscono endpoint per esportare o eliminare i dati dell'Account Google di un utente. Indirizza gli utenti con un Account Google a Google Takeout per esportare i dati di Google Home e alle impostazioni dell'Account Google per gestire l'eliminazione dell'account.

Visualizza i tipi di dispositivi per cui un utente ha concesso le autorizzazioni

Nell'ecosistema Google Home, per la maggior parte dei tipi di dispositivi, gli utenti possono concedere le autorizzazioni per tutti i dispositivi di quel tipo contemporaneamente. Per i tipi di dispositivi sensibili o con limitazioni, come serrature, videocamere o campanelli, gli utenti devono concedere l'autorizzazione singolarmente.

Per determinare se un utente ha concesso l'autorizzazione ad accedere a un tipo di dispositivo sensibile o con limitazioni, utilizza la funzione consentedDeviceTypes() a livello di struttura:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

OkGoogle permissions (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 Home APIs potrebbe non avere accesso a tutti i dispositivi. La tabella seguente descrive come vengono applicate le autorizzazioni in questi casi.

Indicazioni se l'utente revoca le autorizzazioni complete

Se l'utente revoca le autorizzazioni complete, tutte le automazioni esistenti smetteranno di funzionare. Inoltre, se l'utente revoca l'accesso a dispositivi specifici, i comandi iniziali, le condizioni e le azioni associati a questi dispositivi smetteranno di funzionare.

Ogni volta che l'app viene avviata, assicurati di controllare che le autorizzazioni siano ancora attive. Se sono state revocate, assicurati che tutti i dati precedenti vengano rimossi, inclusi quelli memorizzati nella cache dell'applicazione.

Quando l'accesso alla struttura viene revocato, viene inviato un evento StructureAccessRevokedEvent al tuo backend cloud. Consulta la sezione Concessioni della struttura per il flusso di lavoro di revoca end-to-end del cloud e dell'app mobile del partner.