Configura la API de Geospatial en tu app

Dispositivos de realidad extendida correspondientes
Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.
Más información sobre los tipos de dispositivos de realidad extendida →
Lentes de realidad extendida con cable
Lentes con audio y
pantalla
Más información sobre los tipos de dispositivos de realidad extendida →

Para usar la API de Geospatial en tu app, esta debe estar configurada para acceder a la API de ARCore en Google Cloud. Esta API contiene el servicio de posicionamiento visual, que proporciona un posicionamiento preciso con datos de Google Street View.

Esta guía te ayuda a configurar un proyecto de Google Cloud que tenga habilitados los métodos de autorización y la API correctos para acceder a la API.

Configura un proyecto de Google Cloud o usa uno existente

Si tienes un proyecto de Google Cloud existente, selecciónalo.

Ir al selector de proyectos

Si no tienes un proyecto existente, crea uno.

Crear un proyecto nuevo

Habilita la API de ARCore

Para usar la API de ARCore, debes habilitarla en tu proyecto.

Habilita la API de ARCore

Configura la autorización para Google Cloud

Una aplicación para Android puede comunicarse con la API de ARCore con dos métodos de autorización diferentes: la autorización sin clave (OAuth 2.0), que es el método recomendado, y la autorización con clave de API:

  • La autorización sin clave usa una combinación del nombre del paquete de la aplicación y la huella digital de la clave de firma para autorizar tu aplicación.

  • Una clave de API es una cadena que identifica un proyecto de Google Cloud. Por lo general, las claves de API no se consideran seguras, ya que los clientes suelen tener acceso a ellas. Considera usar la autorización sin clave para comunicarte con la API de ARCore.

Autorización sin claves

Para autorizar tu app con la autenticación sin clave, crea IDs de cliente de OAuth 2.0.

  1. En Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales y, luego, selecciona ID de cliente de OAuth en el menú.

  3. Completa los campos obligatorios de la siguiente manera:

    • Tipo de aplicación: Elige Android.
    • Nombre del paquete: Usa el nombre del paquete como se declara en tu AndroidManifest.xml.
    • Huella digital del certificado SHA-1: Obtén las huellas digitales del certificado SHA-1 con las instrucciones que se indican en Autenticación de clientes.

  4. Presiona Crear.

Clave de API

Para crear una clave de API desde la consola de Google Cloud, sigue estos pasos:

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales y, luego, selecciona Clave de API en el menú.

  3. Agrega una restricción de API para la API de ARCore. Para obtener más información, consulta Aplica restricciones de clave de API.

  4. Haz clic en Crear. Se mostrará la cadena a la clave recién creada en el cuadro de diálogo Se creó la clave de API.

En Android Studio, agrega la nueva clave de API a tu proyecto. Incluye la clave de API en un elemento <meta-data> dentro del elemento <application> en el archivo AndroidManifest.xml de tu app:

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

Solicita los permisos necesarios

Para usar la API de Geospatial en ARCore con Jetpack XR, tu app debe solicitar los siguientes permisos de tiempo de ejecución:

En dispositivos móviles, la API de Geospatial también requiere los siguientes permisos:

Cómo acceder a una sesión

Accede a la información geoespacial a través de un Session de Jetpack XR Runtime, que tu app debe crear.

Configura la sesión

La API de Geospatial no está habilitada de forma predeterminada en las sesiones de XR. Tu app debe habilitarla de forma explícita configurando un GeospatialMode en el Session. Los siguientes modos están disponibles:

  • GeospatialMode.SPATIAL: La API de Geospatial está habilitada. La API de Geospatial usa el sistema de posicionamiento visual (VPS), los datos del sistema de posicionamiento global (GPS) y los sensores de movimiento del dispositivo para determinar la posición geoespacial del dispositivo. Este modo no está disponible en dispositivos de anteojos inteligentes.
  • GeospatialMode.INERTIAL: La API de Geospatial está habilitada en el modo de bajo consumo. La API de Geospatial solo usa el GPS y los sensores de movimiento del dispositivo para determinar su pose geoespacial. Este modo solo está disponible en dispositivos de anteojos inteligentes.
  • GeospatialMode.DISABLED: La API de Geospatial está inhabilitada. Cuando se cambia de otro modo a este, la API de Geospatial libera todos los recursos adquiridos y deja de realizar el seguimiento.

No todos los dispositivos admiten todos los modos geoespaciales. Consulta GeospatialMode para obtener más información. Usa XrDevice.isGeospatialSupported para saber si se admite un GeospatialMode determinado.

En la siguiente muestra de código, se indica cómo establecer un GeospatialMode con 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 al usuario que permita el uso de los datos del dispositivo

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

Usa el objeto Geospatial

Una vez que se haya configurado la sesión, obtén el objeto Geospatial con Geospatial.getInstance. Solo usa el objeto Geospatial cuando su estado sea GeospatialTrackingState.RUNNING.

En las siguientes muestras de código, se indica cómo supervisar el estado geoespacial con 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.
        }
    }
}

Información sobre los valores de precisión

Cuando la API de Geospatial está habilitada, proporciona tres valores de precisión: horizontal, vertical y de orientación. Estos valores de exactitud se actualizan con el tiempo y se pueden volver más precisos a medida que se adquieren más datos. Los valores más altos indican una exactitud más baja y se definen como el radio de un nivel de confianza del 68%. En otras palabras, hay un 68% de probabilidades de que el valor real se encuentre dentro del radio dado del valor estimado.

Usa Geospatial.State.horizontalAccuracy, verticalAccuracy y orientationYawAccuracy para obtener los valores de precisión actuales.

Es posible que tu app requiera un nivel específico de precisión para funcionar correctamente. Por ejemplo, es posible que tu app deba esperar hasta que la precisión horizontal sea inferior a 5 metros antes de renderizar contenido virtual. Para aumentar la probabilidad de obtener datos de mayor precisión, tu app debe indicarles a los usuarios que miren a su alrededor, preferentemente a edificios o a otros elementos con un alto nivel de detalle visual que estén presentes en Google Street View. Usa Geospatial.checkVpsAvailability para determinar si el VPS está disponible en la ubicación determinada.

¿Qué sigue?

Cuando la API de Geospatial esté configurada correctamente en tu app, esta podrá hacer lo siguiente: