API Permissions no Android

Antes de usar qualquer uma das APIs Home para Android, o app precisa ter permissão para acessar os dispositivos na casa do usuário, referidos na API como a estrutura. Com a API Permissions, o usuário pode, usando a Conta do Google, conceder aos apps das APIs Home acesso aos dispositivos na casa.

O fluxo de permissão permite que o usuário crie uma estrutura, se ainda não tiver uma configurada , sem precisar usar Google Home app (GHA).

Integrar a API Permissions

Antes de continuar, siga as instruções em Inicializar a casa no Android. A instância homeManager dessa etapa é usada em todos os exemplos de permissões aqui.

Primeiro, registre um ActivityResultCaller com o SDK. Por exemplo, é assim que o app de exemplo lida com isso:

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

Verificar permissões

Antes de solicitar permissões, recomendamos que você verifique se o usuário do app já concedeu consentimento para acessar a estrutura. Para fazer isso, chame o hasPermissions() método da instância Home para receber um Flow de PermissionsState valores:

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 a verificação retornar um PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, isso significa que o usuário ou o aplicativo não tem acesso à estrutura. Se a verificação retornar um PermissionsState de GRANTED, mas uma chamada subsequente para structures() não retornar nenhuma estrutura, isso significa que o usuário revogou o acesso ao app na página de configurações do GHA ou não tem o acesso necessário.

Solicitar permissões

A permissão precisa ser concedida ao seu app para acessar estruturas e dispositivos em uma determinada estrutura.

Se o usuário ainda não tiver concedido permissões, use o requestPermissions() método da instância Home para iniciar a interface de permissões e processar o resultado:

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}")
      }
    }
  }
}

Para que a interface de permissões seja iniciada corretamente, você já precisa ter configurado o OAuth para seu app.

Conceder permissões

Agora você pode executar o app e fazer com que um usuário conceda permissões. O tipo de usuários que podem conceder permissão e os tipos de dispositivos disponíveis para conceder permissões variam dependendo se você registrou o app no Google Home Developer Console.

O registro Developer Console é necessário para publicar um app usando as APIs Home. Não é necessário testar e usar as APIs Home.

Se um app não estiver registrado no Developer Console, ele estará em um estado não verificado. Isso é recomendado para testar o uso das APIs Home:

• Somente os usuários registrados como usuários de teste no console do OAuth podem conceder permissões para o app. Há um limite de 100 usuários de teste para um app não verificado .

• Um app não verificado terá acesso a dispositivos de qualquer tipo compatível com o OAuth para as APIs Home (a lista de tipos de dispositivos no Developer Console). Todos os dispositivos em uma estrutura serão concedidos.

Se um app estiver registrado no Developer Console e tiver sido aprovado para acesso a um ou mais tipos de dispositivos, e a verificação da marca tiver sido concluída para o OAuth, ele estará em um estado verificado. Esse estado é necessário para lançar um app na produção:

• Os limites de usuários de teste não se aplicam mais. Qualquer usuário pode conceder permissão ao app.
• O usuário só pode conceder permissão aos tipos de dispositivos aprovados em o Developer Console.

Agora que o OAuth está configurado, a chamada do app para requestPermissions() aciona as seguintes caixas de diálogo:

1. O usuário é solicitado a selecionar a Conta do Google que quer usar.
2. O usuário é solicitado a selecionar a estrutura a que quer conceder acesso ao app.
   1. Para um app não verificado, todos os tipos de dispositivos compatíveis com as APIs Home estão disponíveis para o app.
   2. Para um app verificado, o usuário só pode conceder permissão aos tipos de dispositivos aprovados em Developer Console.
   3. Para tipos de dispositivos sensíveis que o app tem acesso para gerenciar, o usuário pode restringir o acesso por dispositivo. Por exemplo, se um usuário tiver três fechaduras, ele poderá conceder acesso a apenas uma delas.

Depois que a permissão for concedida, o app poderá usar as APIs Home para ler o estado e controlar os dispositivos na estrutura. Se o usuário não conceder permissão ao app para um determinado tipo de dispositivo ou dispositivo sensível, o app não poderá usar as APIs Home para acessar, controlar ou automatizar.

Alterar permissões

Para conceder permissão para acessar dispositivos em uma estrutura diferente, o seletor de contas pode ser iniciado para permitir que o usuário escolha a Conta do Google e a estrutura para mudar. Durante esse processo, a tela de permissão será apresentada novamente ao usuário, mesmo que o consentimento tenha sido concedido anteriormente.

Isso pode ser feito chamando requestPermissions() novamente com a flag forceLaunch definida como true:

homeManager.requestPermissions(forceLaunch=true)

Revogar permissões

Os usuários podem revogar o acesso concedido anteriormente:

1. Na página " Minha conta" do Google > Dados e privacidade > Apps e serviços de terceiros. Isso revogará o token do OAuth emitido quando o consentimento inicial foi concedido e revogará o acesso a qualquer instância do app que o usuário estava usando em todas as plataformas (smartphones) e estruturas.

   O usuário pode ser direcionado com um link direto para a subpágina Apps e serviços de terceiros usando o seguinte esquema de URL:

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

2. Na página GHA > Configurações > Apps vinculados. Clicar em settings no GHA leva a página Configurações. Nela, clique no bloco Apps vinculados , que leva a uma página semelhante à tela de permissão. Nessa página, o usuário pode remover o acesso ao app. O usuário pode usar essa mesma página para mudar quais tipos de dispositivos ou dispositivos sensíveis específicos estão acessíveis ao app.

Ver os tipos de dispositivos para os quais um usuário concedeu permissões

No ecossistema do Google Home, para a maioria dos tipos de dispositivos, os usuários podem conceder permissões para todos os dispositivos desse tipo de uma só vez. Para tipos de dispositivos sensíveis ou restritos, como fechaduras, câmeras ou campainhas, os usuários precisam conceder permissão individualmente.

Para determinar se um usuário concedeu permissão para acessar um tipo de dispositivo sensível ou restrito, use a função consentedDeviceTypes() no nível da estrutura:

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
            }
        }
    }
}

Permissões do OkGoogle

O okGoogle comando é um comando no nível do dispositivo e pode ser usado para automatizar qualquer dispositivo na estrutura. No entanto, um app das APIs Home pode não ter acesso a todos os dispositivos. A tabela a seguir descreve como as permissões são aplicadas nesses casos.

Orientação se o usuário revogar permissões completas

Se o usuário revogar permissões completas, todas as automações atuais vão parar de funcionar. Além disso, se o usuário revogar o acesso a dispositivos específicos, os iniciadores, condições e ações associados a esses dispositivos vão parar de funcionar.

Sempre que o app for iniciado, verifique se as permissões ainda estão em vigor. Se elas tiverem sido revogadas, remova todos os dados anteriores, incluindo os dados armazenados em cache no aplicativo.