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.

As APIs Home usam o OAuth 2.0 para conceder acesso a dispositivos na estrutura. O OAuth permite que um usuário conceda permissão a um app ou serviço sem expor expor as credenciais de login. Com a API Permissions, o usuário pode usar a Conta do Google para conceder aos apps das APIs Home acesso a dispositivos na casa.

O uso da API Permissions envolve várias etapas no app, no Google Cloud e no Google Home Developer Console:

1. Configurar o OAuth no Google Cloud
   1. Assinar o app
   2. Configurar a tela de consentimento OAuth
   3. Registrar o app e criar credenciais
2. Integrar a API Permissions
   1. Verificar permissões
   2. Solicitar permissões
3. Conceder permissões
   1. Alterar permissões
   2. Revogar permissões

Configurar o OAuth no Google Cloud

Se você já tiver um cliente OAuth verificado, poderá usá-lo sem configurar um novo. Para mais informações, consulte Se você já tem um cliente OAuth.

Assinar o app

1. Gere uma chave OAuth executando o app em Android Studio. Quando você executa ou depura um app no Android Studio, ele gera automaticamente uma chave OAuth destinada ao desenvolvimento e à depuração. Consulte Android Studio: assinar seu build de depuração para uma explicação completa.

   Conecte seu dispositivo móvel à máquina local. Android Studio vai listar seus dispositivos conectados por número de modelo. Selecione seu dispositivo na lista e clique em Run project. Isso cria e instala o app de exemplo no seu dispositivo móvel.

   Para instruções mais detalhadas, consulte Executar apps em um dispositivo de hardware no site para desenvolvedores Android.

   Agora, pare o app em execução.

2. Para conferir a impressão digital SHA-1 do certificado OAuth, siga as instruções detalhadas em Como configurar o OAuth 2.0 / aplicativos nativos / Android no site de ajuda do Google Cloud Console.

Configurar a tela de consentimento OAuth

1. No console do Google Cloud, acesse o painel do seletor de projetos e selecione o projeto que você quer usar para criar credenciais do OAuth.
2. Acesse a página APIs e serviços e clique em Credenciais no menu de navegação.

3. Se você ainda não tiver configurado a tela de consentimento para este projeto do Google Cloud, o botão Configurar tela de consentimento vai aparecer. Nesse caso, configure a tela de consentimento usando o procedimento a seguir. Caso contrário, avance para a próxima seção.

   1. Clique em Configurar tela de consentimento. A página Tela de consentimento do OAuth é exibida.
   2. Dependendo do seu caso de uso, selecione Internal ou External e clique em Create. O painel Tela de consentimento do OAuth é exibido.
   3. Insira informações na página de informações do app de acordo com as instruções na tela e clique em Salvar e continuar. O painel Scopes é exibido.
   4. Não é necessário adicionar escopos. Clique em Salvar e continuar. O painel Test users é exibido.
   5. Se você quiser adicionar usuários para testar o acesso ao app, clique em Adicionar usuários. O painel Adicionar usuários é exibido. Os usuários de teste têm o privilégio de conceder permissões no app.
   6. No campo vazio, adicione um ou mais endereços de e-mail da Conta do Google e clique em Adicionar.
   7. Clique em Salvar e continuar. O painel Summary é exibido.
   8. Revise as informações da tela de consentimento do OAuth e clique em Voltar ao painel.

Consulte Como configurar a tela de consentimento OAuth no site de ajuda do Google Cloud Console para conferir todos os detalhes.

Registrar o app e criar credenciais

Para registrar o app para o OAuth 2.0 e criar credenciais do OAuth, siga as instruções em Como configurar o OAuth 2.0. Você precisa indicar o tipo de app, que é app nativo/Android.

Adicione a impressão digital SHA-1 que você recebeu ao assinar o app ao cliente OAuth configurado no console do Google Cloud seguindo as instruções em Como configurar aplicativos OAuth 2.0 / nativos no site de ajuda do console do Google Cloud.

Com o dispositivo móvel conectado à máquina local, selecione o dispositivo na lista e clique em Run project novamente para executá-lo. Para instruções mais detalhadas, consulte Executar apps em um dispositivo de hardware no site para desenvolvedores Android.

Integrar a API Permissions

Os usuários precisam conceder permissões ao app para acessar dispositivos em uma estrutura específica. Para começar, siga as etapas para inicializar as APIs do Google Home. 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 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. Para acessar o recurso de registro do console, entre em contato com o Technical Account Manager (TAM) do Google.

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.

Se você já tiver um cliente OAuth

Se você já tiver um cliente OAuth verificado para um app publicado, use o cliente OAuth atual para testar as APIs Home.

O registro de Developer Console não é necessário para testar e usar as APIs Home. No entanto, você ainda vai precisar de um registro Developer Console aprovado para publicar o app, mesmo que tenha um cliente OAuth verificado de outra integração.

As seguintes considerações se aplicam:

• Há um limite de 100 usuários ao usar um cliente OAuth existente. Para saber como adicionar usuários de teste, consulte Configurar a tela de consentimento OAuth. Independentemente da verificação do OAuth, há um limite de 100 usuários imposto pelas APIs Home que podem conceder permissões ao seu app. Essa limitação é suspensa após a conclusão do registro de Developer Console.

• ODeveloper Console registration precisa ser enviado para aprovação quando você estiver pronto para restringir as permissões de tipo de dispositivo por meio do OAuth para preparar a atualização do app com as APIs Home.

Para apps Google Cloud que ainda estão com a verificação OAuth pendente, os usuários não podem concluir o fluxo OAuth até que a verificação seja concluída. As tentativas de conceder permissões vão falhar com o seguinte erro:

Access blocked: <Project Name> has not completed the Google verification process.

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.