Guía para desarrolladores de Cloud Anchors para Unity (AR Foundation)

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 Cloud Anchors, asegúrate de comprender cómo funcionan las anclas y las Cloud Anchors.

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 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:

Aloja una Cloud Anchor

Hosting comienza con una llamada a ARAnchorManager.HostCloudAnchorAsync(). ARCore subirá datos visuales, poses de dispositivos y posiciones de anclas a la API de ARCore. Luego, la API procesa esta información para construir un mapa de atributos 3D y, en última instancia, mostrará un ID de Cloud Anchor único para el ancla en el 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 ARAnchorManager.HostCloudAnchorAsync().
  2. Inicia una corrutina para esperar hasta que la promesa produzca un resultado. Consulta Corrutinas en Unity para obtener más información.
  3. Cómo verificar el estado del resultado para determinar si la operación se realizó correctamente o interpretar 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 ARAnchorManagerExtensions.ResolveCloudAnchorAsync()

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

ARCoreExtensions.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, las Cloud Anchors alojadas con funciones de mayor calidad se resuelven con mayor precisión. Usa ARAnchorManagerExtensions.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 segundos anteriores 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 la posición deseada de Cloud Anchor que desee 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 correctamente una Cloud Anchor, aunque es probable que se reduzca la precisión de la postura 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 La calidad de los puntos de atributos identificados a partir de la pose en los segundos anteriores probablemente sea suficiente para que ARCore resuelva correctamente una Cloud Anchor con un alto grado de precisión.

Resolver un ancla alojada previamente

Llama a ARAnchorManagerExtensions.ResolveCloudAnchorAsync() para resolver una Cloud Anchor alojada. 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 Cloud Anchor alojado.

Puedes iniciar soluciones para múltiples Cloud Anchors en secuencia. Puede haber hasta 40 operaciones de Cloud Anchor simultáneas a la vez.

Cancela una operación o quita una Cloud Anchor

Se llama automáticamente a ARCloudAnchor.OnDestroy() cuando se quita el componente ARCloudAnchor del objeto de juego que lo contiene. Esta acción desconectará y liberará el objeto nativo subyacente de Cloud Anchor.

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

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

Valor Descripción
ErrorResolvingCloudIdNotFound No se pudo resolver porque la API de ARCore no pudo encontrar el ID de Cloud Anchor proporcionado.
ErrorHostingDatasetProcessingFailed El hosting falló porque el servidor no pudo procesar correctamente el conjunto de datos para el ancla en cuestión. Vuelve a intentarlo cuando el dispositivo haya recopilado más datos del entorno.
ErrorHostingServiceUnavailable 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 respuesta. Es posible que haya una mala conexión de red, 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.
ErrorInternal Una tarea de hosting o resolución para esta ancla finalizó con un error interno. La app no debería intentar recuperarse de este error.
ErrorNotAuthorized La app no se puede comunicar con la API de ARCore debido a una autorización no válida. Marca Configuración del proyecto > XR > Extensiones de ARCore para una estrategia de autorización válida
ErrorResolvingPackageTooNew No se pudo resolver Cloud Anchor porque el paquete de extensiones de ARCore que se usó para resolverlo es más nuevo que la versión que se usa para alojarlo y no es compatible con ella.
ErrorResolvingPackageTooOld No se pudo resolver Cloud Anchor porque el paquete de extensiones de ARCore que se usó para resolverlo es más antiguo que la versión que se usa para alojarlo y no es compatible con ella.
ErrorResourceExhausted 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 en Google Developers Console.
Success Se completó correctamente una tarea de hosting o de resolución para esta 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 ilimitados N/A proyecto
Solicitudes host ancla 30 minuto Dirección IP y proyecto
Solicitudes resolve ancla 300 minuto Dirección IP y proyecto

Prácticas recomendadas para 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 para intentar alojar un ancla (colocando un objeto, etcétera) De esta forma, el seguimiento tendrá tiempo para estabilizarse.
  • Cuando selecciones una ubicación donde 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 colocada en el centro de interés y mueve el dispositivo. centro de interés 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 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 Anclas debido a que el SDK usa una API de ARCore antigua y obsoleta.

¿Qué sigue?