Guía para desarrolladores de Cloud Anchors para Android (Kotlin/Java)

Obtén más información sobre cómo usar Cloud Anchors en tus propias apps.

Requisitos previos

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

Si eres nuevo en Cloud Anchors, sigue estos pasos:

  • Asegúrate de comprender cómo funcionan las anclas y Cloud Anchors.
  • Lee la quickstart de Cloud Anchors para conocer los requisitos del sistema, la configuración y las instrucciones de instalación.

Habilita la API de ARCore

Antes de usar Cloud Anchors en tu app, primero debes habilitar la API de ARCore en la aplicación.

Habilita las capacidades de Cloud Anchor en la configuración de la sesión

Una vez que se haya habilitado la funcionalidad de Cloud Anchors en tu app, habilita las capacidades de Cloud Anchors en la configuración de la sesión de RA de tu app para que pueda comunicarse con la API de ARCore:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Aloja una Cloud Anchor

El hosting comienza con una llamada a hostCloudAnchorAsync(). ARCore subirá datos visuales, poses del dispositivo y la postura del ancla a la API de ARCore. Luego, la API procesa esta información para construir un mapa de atributos en 3D y, en última instancia, muestra un ID de Cloud Anchor único para el ancla en el dispositivo.

También puedes extender la vida útil de un ancla alojada con la API de Cloud Anchor Management de ARCore.

Tu app debe seguir estos pasos para completar el hosting de una Cloud Anchor:

  1. Llama a hostCloudAnchorAsync().
  2. Espera la devolución de llamada o comprueba de forma continua el estado Future hasta que finalice.
  3. Verifica el estado del resultado para determinar si la operación se realizó correctamente o interpreta el código de error si falló.
  4. Comparte el ID de Cloud Anchor resultante con otros clientes y úsalo para resolver la Cloud Anchor con resolveCloudAnchorAsync().

Comprobar la calidad de la asignación de los puntos de componentes

Session.FeatureMapQuality indica la calidad de los puntos del componente que ARCore ve en los segundos anteriores desde una posición de cámara determinada. Por lo general, las Cloud Anchors alojados con funciones de calidad más alta se resuelven con mayor precisión. Usa Session.estimateFeatureMapQualityForHosting() para obtener una estimación de la calidad del mapa de componentes para una pose de cámara determinada.

Valor Descripción
INSUFFICIENT La calidad de los puntos de atributos identificados a partir de la pose en los segundos previos es baja. Este estado indica que es probable que ARCore tenga más dificultades para resolver Cloud Anchor. Alienta al usuario a mover el dispositivo para que se pueda ver la posición deseada de la Cloud Anchor que desea alojar desde diferentes ángulos.
SUFFICIENT La calidad de los puntos de atributos identificados desde la pose en los segundos anteriores es probable que sea suficiente para que ARCore resuelva correctamente una Cloud Anchor, aunque es probable que se reduzca la exactitud de la pose resuelta. Alienta al usuario a mover el dispositivo para que se pueda ver la posición deseada de la Cloud Anchor que desea alojar desde diferentes ángulos.
GOOD La calidad de los puntos de atributos identificados desde la pose en los segundos anteriores es probable que sea suficiente para que ARCore resuelva correctamente una Cloud Anchor con un alto grado de precisión.

Cómo resolver un ancla alojada previamente

Llama a resolveCloudAnchorAsync() para resolver un Cloud Anchor alojado. La API de ARCore compara periódicamente las características visuales de la escena con el mapa de características 3D del ancla para identificar la posición y la orientación del usuario en relación con el ancla. Cuando encuentra una coincidencia, la API muestra la pose del Cloud Anchor alojado.

Puedes iniciar resoluciones para varias Cloud Anchors en secuencia. Pueden existir hasta 40 operaciones simultáneas de Cloud Anchor a la vez.

Cancela una operación o quita una Cloud Anchor

Llama a cancel() para cancelar una operación pendiente de Cloud Anchor. Llama a detach() para quitar una Cloud Anchor ya resuelta de la app.

Verifica el estado del resultado de una operación de Cloud Anchor

Usa Anchor.CloudAnchorState para verificar el estado del resultado de la operación de hosting o resolución, incluidos los errores.

Valor Descripción
ERROR_CLOUD_ID_NOT_FOUND No se pudo resolver el problema porque la API de ARCore no pudo encontrar el ID de Cloud Anchor proporcionado.
ERROR_HOSTING_DATASET_PROCESSING_FAILED Se produjo un error en el hosting porque el servidor no pudo procesar correctamente el conjunto de datos del ancla especificada. Vuelve a intentarlo cuando el dispositivo haya recopilado más datos del entorno.
ERROR_HOSTING_SERVICE_UNAVAILABLE No se podía acceder a la API de ARCore. Esto puede suceder por varios motivos. Es posible que el dispositivo esté en modo de avión o que no tenga una conexión a Internet que funcione. Es posible que se haya agotado el tiempo de espera de la solicitud enviada al servidor sin respuesta. Es posible que haya una conexión de red deficiente, falta de disponibilidad de DNS, problemas de firewall o algún otro problema que pueda afectar la capacidad del dispositivo para conectarse a la API de ARCore.
ERROR_INTERNAL Una tarea de hosting o resolución para este ancla finalizó con un error interno. La app no deberá intentar recuperarse de este error.
ERROR_NOT_AUTHORIZED La autorización proporcionada por la aplicación no es válida. Consulta Solución de problemas con la autorización de la API de ARCore.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW No se pudo resolver Cloud Anchor porque la versión del SDK que se usó para resolver el ancla es más reciente que la versión que se usa para alojarla y no es compatible con ella.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD No se pudo resolver Cloud Anchor porque la versión del SDK que se usó para resolver el ancla es anterior a la versión que se usa para alojarla y no es compatible con ella.
ERROR_RESOURCE_EXHAUSTED La aplicación agotó la cuota de solicitudes asignada al proyecto de Google Cloud determinado. Solicita una cuota adicional para la API de ARCore de tu proyecto en Google Play Console.
SUCCESS Una tarea de hosting o resolución para esta ancla se completó correctamente.

Cuotas de la API para alojar y resolver solicitudes

La API de ARCore tiene las siguientes cuotas para el ancho de banda de solicitudes:

Tipo de cuota Máximo Duración Se aplica a
Cantidad de anclas ilimitados No disponible proyecto
Solicitudes host fijas 30 minuto Dirección IP y proyecto
Fijar solicitudes resolve 300 minuto Dirección IP y proyecto

Prácticas recomendadas para una buena experiencia del usuario

Indica a los usuarios que hagan lo siguiente para garantizar una buena experiencia del usuario en tu app:

  • Espera unos segundos después de que se inicie la sesión antes de intentar alojar un ancla (colocando un objeto, etcétera). De esta manera, el seguimiento puede estabilizarse.
  • Al seleccionar una ubicación para alojar el ancla, intenta encontrar un área con características visuales que se puedan distinguir fácilmente entre sí. Para obtener mejores resultados, evita las superficies reflectantes o que carezcan de características visuales, como paredes blancas en blanco.

  • Mantén la cámara entrenada en el centro de interés y mueve el dispositivo alrededor de este para mapear el entorno desde diferentes ángulos y mantener más o menos la misma distancia física que lo haces. Esto ayudará a capturar más datos visuales y lograr que la resolución sea más sólida.

  • Asegúrate de que haya suficiente iluminación en el entorno real mientras alojas y resuelves Cloud Anchors.

Política de baja

  • Las apps compiladas con el SDK de ARCore 1.12.0 o versiones posteriores están cubiertas por la política de baja de la API de Cloud Anchor.
  • Las apps compiladas con el SDK 1.11.0 o versiones anteriores de ARCore no pueden alojar ni resolver Cloud Anchors debido al uso de una API de ARCore antigua y obsoleta.

¿Qué sigue?