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á deu consentimento. 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 ->
    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 a verificação retornar um PermissionsState de NOT_GRANTED ou PERMISSIONS_STATE_UNAVAILABLE, solicite permissões. 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), e você precisa solicitar permissões. Caso contrário, o usuário já tem acesso.

Solicitar permissões

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

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 no 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 receberão 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.
   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.