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

Aprende a 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 es la primera vez que usas los anclas de Cloud, haz lo siguiente:

Habilita la API de ARCore

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

Habilita las funciones de ancla de Cloud en la configuración de la sesión

Una vez que se habilite la funcionalidad de Cloud Anchors en tu app, habilita sus capacidades en la configuración de sesiones de RA de la 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

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

También puedes extender la vida útil de una 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 verifica continuamente el estado Future hasta que termines.
  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. Compartir el ID de Cloud Anchor resultante con otros clientes y usarlo para resolver el problema con Cloud Anchor resolveCloudAnchorAsync()

Comprobar la calidad de la asignación de los puntos del atributo

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

Valor Descripción
INSUFFICIENT La calidad de los puntos de características identificados a partir de la pose en los últimos segundos es baja. Este estado indica que es probable que ARCore tenga más dificultades para resolver Cloud Anchor. Pídele al usuario que mueva el dispositivo para que la posición deseada de la ancla de Cloud que desea alojar se pueda ver desde diferentes ángulos.
SUFFICIENT Es probable que la calidad de los puntos de atributos identificados a partir de la pose en los segundos anteriores sea suficiente para que ARCore resuelva con éxito una Cloud Anchor, aunque es probable que se reduzca la precisión de la postura resuelta. Pídele al usuario que mueva el dispositivo para que la posición deseada de la ancla de Cloud que desea alojar se pueda ver desde diferentes ángulos.
GOOD Es probable que la calidad de los puntos de características identificados a partir de la pose en los últimos segundos sea suficiente para que ARCore resuelva correctamente una Cloud Anchor con un alto grado de precisión.

Cómo resolver un ancla alojada anteriormente

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 atributos 3D del ancla para determinar 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 ancla de Cloud alojada.

Puedes iniciar soluciones para múltiples Cloud Anchors en secuencia. Se pueden realizar 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 de la app un ancla de Cloud ya resuelta.

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

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

Valor Descripción
ERROR_CLOUD_ID_NOT_FOUND No se pudo resolver porque la API de ARCore no pudo encontrar el ID de Cloud Anchor proporcionado.
ERROR_HOSTING_DATASET_PROCESSING_FAILED No se pudo alojar el contenido porque el servidor no pudo procesar correctamente el conjunto de datos del ancla determinada. Vuelve a intentarlo después de que el dispositivo haya recopilado más datos del entorno.
ERROR_HOSTING_SERVICE_UNAVAILABLE No se pudo 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 recibir respuesta. Es posible que haya una conexión de red deficiente, que el DNS no esté disponible, que haya problemas con el firewall o cualquier otro problema que pueda afectar la capacidad del dispositivo para conectarse a la API de ARCore.
ERROR_INTERNAL Una tarea de alojamiento o resolución para este ancla finalizó con un error interno. La app no debería intentar recuperarse de este error.
ERROR_NOT_AUTHORIZED La autorización que proporcionó la aplicación no es válida. Consulta Soluciona problemas de autorización de la API de ARCore.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW No se pudo resolver el ancla de Cloud porque la versión del SDK que se usó para resolverla es más reciente que la versión que se usó para alojarla y no es compatible con ella.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD No se pudo resolver el ancla de Cloud porque la versión del SDK que se usó para resolverla es anterior a la versión que se usó 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. Debes solicitar una cuota adicional para la API de ARCore para tu proyecto desde Google Play Console.
SUCCESS Se completó correctamente una tarea de alojamiento o resolución para este ancla.

Cuotas de API para solicitudes de host y resolución

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 unlimited N/A proyecto
Solicitudes host ancla 30 minuto Dirección IP y proyecto
Cómo fijar solicitudes de resolución 300 minuto Dirección IP y proyecto

Prácticas recomendadas para lograr una buena experiencia del usuario

Indícales a los usuarios que hagan lo siguiente para garantizar una buena experiencia en tu app:

  • Espera unos segundos después de que comience la sesión antes de intentar alojar un ancla (colocando un objeto, etcétera). Esto le da tiempo al seguimiento para estabilizarse.
  • Cuando selecciones una ubicación para alojar al ancla, intenta encontrar un área con características visuales que se distingan fácilmente entre sí. Para obtener mejores resultados, evita las superficies reflectantes o las que carecen de elementos visuales, como las paredes blancas sin ningún elemento.

  • Mantén la cámara enfocada en el centro de interés y mueve el dispositivo alrededor de él para asignar el entorno desde diferentes ángulos y mantener aproximadamente la misma distancia física mientras lo haces. Esto ayudará a capturar más datos visuales y a 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 de ARCore 1.11.0 o versiones anteriores no pueden alojar ni resolver anclas de Cloud debido a que el SDK usa una API de ARCore anterior y obsoleta.

¿Qué sigue?