Cómo habilitar la API de Geospatial en tu app para Android (Kotlin/Java)

Configura la app para que pueda usar la API de Geospatial.

Requisitos previos

Asegúrate de comprender los conceptos fundamentales de la RA y cómo configurar una sesión de ARCore antes de continuar.

App y codelab de ejemplo

En este video, se explican los pasos para crear una app que muestre datos geoespaciales y coloque contenido en ubicaciones reales con la API de Geospatial.

También puedes seguir la documentación del codelab de Geospatial para realizar los mismos pasos. Para ejecutar la app de ejemplo creada en el video, consulta la Guía de inicio rápido de ARCore Geospatial.

Consulta la Introducción a la API de Geospatial para obtener más información sobre la API de Geospatial.

Si es la primera vez que desarrollas con ARCore, consulta Primeros pasos para obtener información sobre los requisitos de software y hardware, las necesidades previas y otra información específica de las plataformas que usas.

Asegúrate de que tu entorno de desarrollo cumpla con los requisitos del SDK de ARCore, como se describe en la Guía de inicio rápido.

Habilita la API de ARCore

Antes de usar el sistema de posicionamiento visual (VPS) en tu app, primero debes habilitar la API de ARCore en un proyecto de Google Cloud nuevo o existente. Este servicio se encarga de alojar, almacenar y resolver las anclas geoespaciales.

Se prefiere la autorización sin llave, pero también se admite la autorización de la clave de API.

Agrega las bibliotecas requeridas a tu app

Después de autorizar a tu app para que llame a la API de ARCore, debes agregar bibliotecas para habilitar las funciones geoespaciales en tu app.

En el archivo build.gradle de tu app, configura los Servicios de Google Play para incluir la biblioteca de ubicación de los Servicios de Play.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

Habilita las funciones geoespaciales en la configuración de la sesión

Antes de crear la sesión, cambia el GeospatialMode en la configuración de la sesión a ENABLED:

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

Mientras el modo Geospatial está configurado en ENABLED, la aplicación puede obtener información geográfica del sistema de posicionamiento visual (VPS).

Solicitar al usuario que permita el uso de datos del dispositivo

Las apps que usan la API de ARCore Geospatial deben presentarle al usuario un mensaje para que acepte y permita el uso de los datos de su dispositivo. Consulta los requisitos de privacidad del usuario para obtener más información.

Cómo verificar la compatibilidad del dispositivo

No todos los dispositivos que admiten ARCore también admiten la API de Geospatial, como se describe en la Guía de inicio rápido.

Para verificar la compatibilidad del dispositivo del usuario, llama a Session.checkGeospatialModeSupported(). Si esto muestra un valor falso, no intentes configurar la sesión (más abajo), ya que, de lo contrario, se arrojará un UnsupportedConfigurationException.

Cómo solicitar permisos de ubicación al usuario durante el tiempo de ejecución

Tu app debe solicitar permisos de ubicación durante el tiempo de ejecución.

Para usar la API de ARCore Geospatial, tu app debe registrar los siguientes permisos adicionales:

  • ACCESS_FINE_LOCATION para determinar con precisión la ubicación del usuario.

  • ACCESS_COARSE_LOCATION para determinar de forma imprecisa la ubicación del usuario y cumplir con los requisitos de privacidad del usuario. Sin embargo, la API de Geospatial no se puede configurar para funcionar con la ubicación aproximada, y las solicitudes a la API fallarán cuando el usuario haya configurado este permiso. Obtenga más información a continuación.

  • ACCESS_INTERNET para comunicarte con el servicio de la API de ARCore Geospatial

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

En los dispositivos que ejecutan Android 12 o versiones posteriores, los usuarios pueden solicitar que tu app tenga acceso solo a información de ubicación aproximada. Para admitir esta solicitud, tu app debe tener configurado el permiso ACCESS_COARSE_LOCATION, junto con ACCESS_FINE_LOCATION, como se muestra más arriba. Debes configurar ambos permisos de ubicación.

Sin embargo, cuando los usuarios especifican la ubicación aproximada, esto evita que la API de Geospatial obtenga la ubicación precisa que requiere. El servicio Geospatial no se permitirá configurar si tu app solo le proporciona la ubicación aproximada. Tu app no puede usar la API de Geospatial con la ubicación aproximada.

Cómo verificar la disponibilidad geoespacial en la ubicación actual del dispositivo

Dado que la API de Geospatial usa una combinación de VPS y GPS para determinar una posición geoespacial, la API se puede usar siempre que el dispositivo pueda determinar su ubicación. En áreas con baja precisión del GPS, como espacios interiores y entornos urbanos densos, la API se basará en la cobertura de VPS para generar poses de alta precisión. En condiciones típicas, se espera que la VPS proporcione una precisión de posición de aproximadamente 5 metros y una precisión de rotación de 5 grados. Usa Session.checkVpsAvailabilityAsync() para determinar si una ubicación determinada tiene cobertura de VPS.

La API de Geospatial también se puede usar en áreas que no tienen cobertura VPS. En ambientes al aire libre con pocas obstrucciones por encima o ninguna, el GPS puede ser suficiente para generar una postura con alta precisión.

¿Qué sigue?