Configurar a API Geospatial no seu app

Dispositivos XR relevantes
Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.
Saiba mais sobre esses dispositivos →
Óculos XR com fio
Óculos com áudio e
tela
Saiba mais sobre esses dispositivos →

Para usar a API Geospatial no seu app, ele precisa estar configurado para acessar a API ARCore no Google Cloud. Essa API contém o Serviço de posicionamento visual, que fornece um posicionamento preciso usando dados do Google Street View.

Este guia ajuda você a configurar um projeto na nuvem do Google Cloud que tenha ativado a API e os métodos de autorização corretos para acessar a API.

Configurar um projeto na nuvem do Google ou usar um projeto atual

Se você já tiver um projeto do Google Cloud, selecione-o.

Acessar o seletor de projetos

Se você não tiver um projeto, crie um.

Criar um projeto

Ativar a API ARCore

Para usar a API ARCore, é necessário ativá-la no seu projeto.

Ativar a API ARCore

Configurar a autorização para o Google Cloud

Um app Android pode se comunicar com a API ARCore usando dois métodos de autorização diferentes: a autorização sem chave (OAuth 2.0), que é o método recomendado, e a autorização de chave de API:

  • A autorização sem chave usa uma combinação do nome do pacote do aplicativo e da impressão digital da chave de assinatura para autorizar o aplicativo.

  • Uma chave de API é uma string que identifica um projeto na nuvem do Google Cloud. As chaves de API geralmente não são consideradas seguras, porque costumam ser acessíveis aos clientes. Considere usar a autorização sem chave para se comunicar com a API ARCore.

Autorização sem chave

Para autorizar seu app usando a autenticação sem chave, crie IDs do cliente OAuth 2.0.

  1. No Google Cloud, acesse a página Credenciais.

    Ir para Credenciais

  2. Clique em Criar credenciais e selecione ID do cliente OAuth no menu.

  3. Preencha os campos obrigatórios da seguinte maneira:

    • Tipo de aplicativo: escolha Android.
    • Nome do pacote: use o nome do pacote conforme declarado no AndroidManifest.xml.
    • Impressão digital do certificado SHA-1: obtenha impressões digitais do certificado SHA-1 usando as instruções em Autenticação do cliente.

  4. Pressione Criar.

Chave de API

Para criar uma chave de API no console do Google Cloud, siga estas etapas:

  1. No console do Google Cloud, acesse a página Credenciais:

    Ir para Credenciais

  2. Clique em Criar credenciais e, em seguida, selecione a chave de API no menu.

  3. Adicione uma restrição de API para a API ARCore. Para mais informações, consulte Aplicar restrições de chave de API.

  4. Clique em Criar. A caixa de diálogo Chave de API criada mostra a string da chave recém-criada.

No Android Studio, adicione a nova chave de API ao seu projeto. Inclua a chave de API em um elemento <meta-data> no elemento <application> no AndroidManifest.xml do app:

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

Solicitar as permissões necessárias

Para usar a API Geospatial no ARCore com o Jetpack XR, seu app precisa solicitar as seguintes permissões de execução:

Em dispositivos móveis, a API Geospatial também requer as seguintes permissões:

Acessar uma sessão

Acesse informações geoespaciais usando um ambiente de execução do Jetpack XR Session, que seu app precisa criar.

Configurar a sessão

A API Geospatial não é ativada por padrão em sessões de XR. Seu app precisa ativá-lo explicitamente configurando um GeospatialMode no Session. Os seguintes modos estão disponíveis:

  • GeospatialMode.SPATIAL: a API Geospatial está ativada. A API Geospatial usa dados do Sistema de Posicionamento Visual (VPS), do Sistema de Posicionamento Global (GPS) e dos sensores de movimento do dispositivo para determinar a pose geoespacial do dispositivo. Esse modo não está disponível em dispositivos de óculos inteligentes.
  • GeospatialMode.INERTIAL: a API Geospatial está ativada no modo de baixo consumo. A API Geospatial usa apenas o GPS e os sensores de movimento do dispositivo para determinar a pose geoespacial do dispositivo. Esse modo está disponível apenas em dispositivos de óculos inteligentes.
  • GeospatialMode.DISABLED: a API Geospatial está desativada. Ao fazer a transição de outro modo para esse, a API Geospatial libera todos os recursos adquiridos e interrompe o rastreamento.

Nem todos os dispositivos são compatíveis com todos os modos geoespaciais. Veja mais informações em GeospatialMode. Use XrDevice.isGeospatialSupported para saber se um determinado GeospatialMode é compatível.

O exemplo de código a seguir demonstra como definir um GeospatialMode usando Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}

Solicitar que o usuário permita o uso de dados do dispositivo

Os apps que usam a API Geospatial com o ARCore para Jetpack XR precisam apresentar ao usuário uma solicitação para confirmar e permitir o uso de dados do dispositivo. Consulte as normas de privacidade do usuário para mais informações.

Usar o objeto geoespacial

Depois que a sessão for configurada, use Geospatial.getInstance para receber o objeto Geospatial. Use o objeto Geospatial somente quando o estado dele for GeospatialTrackingState.RUNNING.

Os exemplos de código a seguir mostram como monitorar o estado geoespacial usando Geospatial.state.

Compose XR

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}

SceneCore

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}

Entender os valores de precisão

Quando a API Geospatial está ativada, ela fornece três valores de precisão: horizontal, vertical e de orientação. Esses valores de precisão são atualizados ao longo do tempo e podem ser mais precisos à medida que mais dados são adquiridos. Valores maiores indicam menor precisão e são definidos como o raio de um nível de confiança de 68%. Em outras palavras, há uma probabilidade de 68% de que o valor verdadeiro esteja dentro do raio fornecido do valor estimado.

Use Geospatial.State.horizontalAccuracy, verticalAccuracy e orientationYawAccuracy para saber os valores de precisão atuais.

Seu app pode exigir um nível específico de precisão para funcionar corretamente. Por exemplo, seu app pode esperar até que a precisão horizontal seja menor que 5 metros antes de renderizar o conteúdo virtual. Para aumentar a probabilidade de obter dados de maior precisão, seu app precisa instruir os usuários a olhar ao redor, de preferência para edifícios ou outros elementos com muitos detalhes visuais que estejam presentes no Google Street View. Use Geospatial.checkVpsAvailability para determinar se o VPS está disponível no local especificado.

A seguir

Quando a API Geospatial está configurada corretamente no app, ele pode fazer o seguinte: