API Permissions

Antes de usar qualquer uma das APIs Home, 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 usar a Conta do Google para conceder aos apps das APIs Home acesso aos dispositivos da casa.

Integrar a API Permissions

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

Primeiro, registre um ActivityResultCaller com o SDK. Por exemplo, o app de exemplo lida com isso da seguinte maneira:

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

Verificar permissões

Antes de solicitar permissões, recomendamos verificar se o usuário do app já concedeu o consentimento. Para fazer isso, chame o método hasPermissions() da instância da casa 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 terá revogado o acesso ao app pela página de configurações Google Home app (GHA), e você precisará solicitar permissões. Caso contrário, o usuário já deve ter acesso.

Solicitar permissões

A permissão precisa ser concedida ao app para que ele acesse estruturas e dispositivos em uma determinada estrutura.

Se o usuário ainda não tiver concedido permissões, use o método requestPermissions() da instância da casa para iniciar a IU 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 usuário de permissões seja iniciada corretamente, você precisa ter configurado o OAuth para o app.

Conceder permissões

Agora você pode executar o app e ter permissões concedidas pelo usuário. O tipo de usuário que pode conceder a permissão e os tipos de dispositivo disponíveis para conceder permissões variam de acordo com se você registrou seu app no Google Home Developer Console.

O registro de 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. Recomendamos o seguinte para testar o uso das APIs Home:

• Somente usuários registrados como usuários de teste no console 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 que tenha suporte do 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 dispositivo, 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 teste para usuários 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 dispositivo que foram 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 é solicitado a selecionar a estrutura a que quer conceder acesso ao app.
   1. Para um app não verificado, todos os tipos de dispositivo compatíveis com as APIs Home estão disponíveis para o app.
   2. Em um app verificado, o usuário pode conceder permissão apenas aos tipos de dispositivo que foram 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 da Página inicial 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 sensível, o app não poderá usar as APIs Home para acessar, controlar ou automatizar o 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 consentimento será mostrada 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"Google MyAccounts " > 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.

2. Na página GHA > Configurações > Apps vinculados. Clicar em settings no GHA leva você à página Configurações. Em seguida, clique no bloco Apps vinculados, que leva você a uma página semelhante à tela de consentimento. 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 dispositivo ou dispositivos sensíveis específicos podem ser acessados pelo app.

3. Na página "Aplicativos vinculados" diretamente na Web.

Permissões do OkGoogle

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