API Permissions no Android

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

O fluxo de permissão permite que o usuário crie uma estrutura e atribua o endereço dela, caso ainda não tenha sido configurado, sem precisar usar o 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 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, 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 estruturas, isso significa que o usuário revogou o acesso ao app pela página de configurações do GHA ou que o usuário não tem o acesso necessário.

Solicitar permissões

É preciso conceder permissão ao app para acessar 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 do 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, é necessário já ter configurado o OAuth para o app.

A interface de consentimento de permissões é renderizada na localidade configurada com HomeClient.setLocale() ou, se não estiver definida, usa como padrão a localidade do app ou do dispositivo. Para mostrar a tela de permissão em um idioma específico, chame setLocale() na instância HomeClient antes de chamar requestPermissions(). Para mais informações, consulte Configurar a localidade do app.

Conceder permissões

Agora você pode executar o app e fazer com que um usuário conceda permissões. O tipo de usuário que pode conceder permissão e os tipos de dispositivo disponíveis para conceder permissões variam de acordo com o registro do app no Google Home Developer Console.

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

Se um app não estiver registrado no Developer Console, ele vai ficar 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 que sejam compatíveis 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 acessar um ou mais tipos de dispositivo, e a verificação de marca tiver sido concluída para o OAuth, ele estará em um estado verificado. Esse estado é necessário para lançar um app em 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 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 precisa selecionar a estrutura que quer conceder acesso ao app.
   1. Para um app não verificado, todos os tipos de dispositivos compatíveis com as APIs do Google Home estão disponíveis.
   2. Para um app verificado, o usuário pode conceder permissão apenas aos tipos de dispositivo aprovados em Developer Console.
   3. Para tipos de dispositivos sensíveis que o app pode 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 do Google 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 específico de dispositivo ou 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 as quais quer mudar. Durante esse processo, a tela de permissão será apresentada ao usuário novamente, mesmo que o consentimento tenha sido concedido anteriormente.

Para isso, chame requestPermissions() novamente com forcePermissionFlow definido como ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Mudar permissões com indicação de estrutura

A indicação de estrutura permite que um app pré-selecione uma estrutura específica ou restrinja a lista de estruturas disponíveis ao solicitar uma mudança incremental nas permissões das APIs do Google Home do usuário. Ao transmitir parâmetros de estrutura para a solicitação de autorização, a caixa de diálogo de permissões vai se concentrar automaticamente na estrutura escolhida, reduzindo o atrito do usuário e evitando erros de configuração.

A indicação de estrutura é gerenciada usando a classe de dados ConsentScreenOptions. A classe ConsentScreenOptions aceita os seguintes parâmetros de configuração:

• structureId: o ID da estrutura específica a ser pré-selecionado na caixa de diálogo de permissão. Para isso, verifique as propriedades da estrutura que está sendo atualizada.
• allowedStructureIds: uma lista de IDs de estrutura. Se fornecido, a caixa de diálogo de permissão vai filtrar as estruturas disponíveis para mostrar apenas as que estão nessa lista. Isso pode ser deixado sem especificação na maioria dos casos, a menos que você queira garantir que o usuário permaneça em uma lista de estruturas já concedidas.
• allowStructureChange: determina se o usuário tem permissão para mudar a estrutura pré-selecionada. Defina como true se pelo menos um de allowedStructureIds e structureId for especificado na maioria dos casos para oferecer um comportamento natural ao usuário.

Transmita esse objeto como um parâmetro opcional na chamada requestPermissions(), com forcePermissionFlow definido como ForcePermissionFlow.FORCE_LAUNCH:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

A tela de permissão será apresentada ao usuário já filtrada para a estrutura indicada no objeto ConsentScreenOptions.

Permitir que o usuário mude de estrutura com a indicação de estrutura

Se um usuário tiver várias estruturas em um app e você quiser pré-selecionar uma, mas permitir que ele alterne entre as estruturas disponíveis, ative as mudanças de estrutura com a flag allowStructureChange e forneça uma lista de estruturas em allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

Revogar permissões

Os usuários podem revogar o acesso concedido anteriormente:

1. Nas configurações da Conta do Google > Dados e privacidade > Apps e serviços de terceiros. Isso vai revogar o token OAuth emitido quando o consentimento inicial foi concedido e 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 você a uma página semelhante à tela de permissão. Nessa página, o usuário pode remover o acesso ao app e mudar quais tipos de dispositivos ou dispositivos sensíveis específicos podem ser acessados pelo app.

Exclusão e exportação de dados do usuário

A plataforma gerencia automaticamente a exclusão de dados de back-end quando um usuário exclui a Conta do Google ou sai de uma estrutura:

• Se o usuário excluído for o único proprietário de uma estrutura, a plataforma vai excluir a estrutura e as associações de dispositivos dela.
• Se outros proprietários permanecerem em uma estrutura compartilhada, a estrutura e seus dispositivos compartilhados persistirão para os membros restantes. A plataforma remove a assinatura do usuário que saiu e desvincula todos os dispositivos de terceiros Cloud-to-cloud conectados apenas pelas credenciais desse usuário.
• A exclusão da conta remove imediata e permanentemente os dados da estrutura e as permissões de aplicativos do usuário. Mesmo que o usuário recupere a Conta do Google, as estruturas e permissões não serão restauradas.

As APIs do Google Home não fornecem endpoints para exportar ou excluir dados da Conta do Google de um usuário. Oriente os usuários com uma Conta do Google a acessar o Google Takeout para exportar os dados do Google Home e as configurações da Conta do Google para gerenciar a exclusão da conta.

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 dispositivo, 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 comando okGoogle é de nível de 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 as permissões completas

Se o usuário revogar as 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, as ativações, condições e ações associadas a eles 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, verifique se todos os dados anteriores foram removidos, incluindo os dados armazenados em cache no aplicativo.

Quando o acesso à estrutura é revogado, um StructureAccessRevokedEvent é enviado ao back-end na nuvem. Consulte Estruturar concessões para o fluxo de trabalho de revogação de ponta a ponta do app para dispositivos móveis e da nuvem do parceiro.