API Permissions no Android

Antes de usar qualquer API Home para Android, o app precisa ter permissão para acessar 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 dele.

Integrar a API Permissions

Antes de continuar, siga as etapas 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 amostra 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 método hasPermissions() da instância Home para receber um Flow de valores 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 a verificação retornar um PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, 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 estruturas, o usuário revogou o acesso ao app na página de configurações Google Home app (GHA) ou não tem o acesso necessário.

Solicitar permissões

É necessário conceder permissão ao app para acessar estruturas e dispositivos dentro de uma estrutura específica.

Se o usuário ainda não tiver concedido permissões, use o método requestPermissions() 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ê 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 isso variam dependendo se você registrou o app no Google Home Developer Console.

O registro do 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 vai ficar em um estado não verificado. Recomendado para testar o uso das APIs Home:

• Somente 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 em Developer Console). Todos os dispositivos em uma estrutura vão receber acesso.

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 de marca tiver sido concluída para OAuth, ele estará no estado verificado. Esse estado é necessário para lançar um app em produção:

• Os limites de usuários de teste não são mais aplicáveis. Qualquer usuário pode conceder permissão ao app.
• O usuário só pode conceder permissão aos tipos de dispositivos aprovados no 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 precisa selecionar a Conta do Google que quer usar.
2. O usuário precisa 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 bloqueios, ele poderá conceder acesso a apenas um deles.

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 tipo de dispositivo específico ou um dispositivo sensível, o app não poderá usar as APIs Home para acessar, controlar ou automatizar esse dispositivo.

Alterar permissões

Para conceder permissão de acesso a 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 alternar. Durante esse processo, a tela de permissão será apresentada novamente ao usuário, mesmo que o consentimento tenha sido concedido anteriormente.

Para isso, chame 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 Minhas contas do Google > Dados e privacidade > Apps e serviços de terceiros. Isso revoga o token OAuth emitido quando o consentimento inicial foi concedido e revoga 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. Clique em settings no GHA para acessar a página Configurações. Em seguida, clique no bloco Apps vinculados, que leva a uma página semelhante à tela de consentimento. Nessa página, o usuário pode remover o acesso ao app e mudar os tipos de dispositivos ou dispositivos sensíveis específicos que podem ser acessados pelo app.

Permissões do OkGoogle

O comando okGoogle é usado 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.