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

Obtén información para usar anclas de Cloud en tus propias apps.

Requisitos previos

Asegúrate de comprender los conceptos fundamentales de la 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:

  • Asegúrate de comprender cómo funcionan las anclas y las anclas de Cloud.
  • Lee la guía de inicio rápido 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 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, poses del dispositivo y la pose de la ancla 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 al dispositivo.

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

Tu app debe seguir estos pasos para completar el alojamiento de un ancla de Cloud:

  1. Llama a hostCloudAnchorAsync().
  2. Espera a que se realice la devolución de llamada o revisa el estado Future de forma continua hasta que se complete.
  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 el Cloud Anchor con resolveCloudAnchorAsync().

Verifica la calidad de la asignación de puntos de referencia

Session.FeatureMapQuality indica la calidad de los puntos del entorno que ARCore ve en los últimos segundos desde una posición 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 características para una posición de cámara determinada.

Valor Descripción
INSUFFICIENT La calidad de los puntos de características identificados a partir de la pose en los segundos anteriores es baja. Este estado indica que ARCore probablemente tendrá más dificultades para resolver la ancla de Cloud. 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 características identificados a partir de la pose en los últimos segundos sea suficiente para que ARCore resuelva correctamente una ancla de Cloud, aunque es probable que se reduzca la precisión de la pose resuelta. Alienta al usuario a mover el dispositivo para que la posición deseada de Cloud Anchor que desee 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 características 3D del ancla para determinar la posición y la orientación del usuario en relación con la ancla. Cuando encuentra una coincidencia, la API muestra la pose del ancla de Cloud alojada.

Puedes iniciar resoluciones para varios anclas de Cloud en secuencia. Puede haber hasta 40 operaciones de Cloud Anchor simultáneas a la vez.

Cancela una operación o quita un ancla de Cloud

Llama a cancel() para cancelar una operación pendiente de Cloud Anchor. Llama a detach() para quitar de la app una Cloud Anchor 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 que se envió al servidor sin recibir respuesta. Es posible que haya una conexión de red deficiente, falta de disponibilidad de DNS, problemas de 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 debe 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 de host de 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

Instruye a los usuarios a hacer 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). De esta forma, el seguimiento tendrá tiempo 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 no tengan 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 ese centro para mapear el entorno desde diferentes ángulos y mantener más o menos la misma distancia física. Esto ayudará a capturar más datos visuales y hará 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 las anclas de Cloud.

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 Anclas debido a que el SDK usa una API de ARCore antigua y obsoleta.

¿Qué sigue?