Guide du développeur Cloud Anchors pour Android (Kotlin/Java)

Découvrez comment utiliser Cloud Anchors dans vos propres applications.

Prérequis

Avant de continuer, assurez-vous de bien comprendre les concepts fondamentaux de la RA et de savoir configurer une session ARCore.

Si vous débutez avec les Cloud Anchors:

  • Assurez-vous de bien comprendre le fonctionnement des ancres et des ancres cloud.
  • Consultez le guide de démarrage rapide de Cloud Anchors pour connaître la configuration système requise, et obtenir des instructions de configuration et d'installation.

Activer l'API ARCore

Avant d'utiliser Cloud Anchors dans votre application, vous devez d'abord activer l'API ARCore dans votre application.

Activer les fonctionnalités Cloud Anchor dans la configuration de la session

Une fois la fonctionnalité Cloud Anchors activée dans votre application, activez les fonctionnalités Cloud Anchors dans la configuration de la session AR de votre application afin qu'elle puisse communiquer avec l'API 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)

Héberger une ancre cloud

L'hébergement commence par un appel à hostCloudAnchorAsync(). ARCore importe les données visuelles, les positions de l'appareil et la position de l'ancre dans l'API ARCore. L'API traite ensuite ces informations pour créer une carte de fonctionnalités 3D, et renvoie finalement un ID d'ancre cloud unique pour l'ancre de l'appareil.

Vous pouvez également prolonger la durée de vie d'une ancre hébergée à l'aide de l'API Cloud Anchor Management ARCore.

Pour héberger une balise Cloud, votre application doit suivre ces étapes:

  1. Appelez hostCloudAnchorAsync().
  2. Attendez le rappel ou vérifiez continuellement l'état Future jusqu'à ce qu'il soit terminé.
  3. Vérifiez l'état du résultat pour déterminer si l'opération a réussi ou interprétez le code d'erreur si elle a échoué.
  4. Partagez l'ID d'ancre cloud obtenu avec d'autres clients et utilisez-le pour résoudre l'ancre cloud avec resolveCloudAnchorAsync().

Vérifier la qualité de la cartographie des points d'intérêt

Session.FeatureMapQuality indique la qualité des points de caractéristiques vus par ARCore au cours des quelques secondes précédentes à partir d'une position d'appareil photo donnée. Les ancres cloud hébergées à l'aide de fonctionnalités de meilleure qualité sont généralement résolues plus précisément. Utilisez Session.estimateFeatureMapQualityForHosting() pour obtenir une estimation de la qualité de la carte de caractéristiques pour une position de caméra donnée.

Valeur Description
INSUFFICIENT La qualité des points d'intérêt identifiés à partir de la pose au cours des quelques secondes précédentes est faible. Cet état indique qu'ARCore aura probablement plus de difficultés à résoudre l'ancre Cloud. Encouragez l'utilisateur à déplacer l'appareil de sorte que la position souhaitée de l'ancre cloud qu'il souhaite héberger puisse être vue sous différents angles.
SUFFICIENT La qualité des points d'intérêt identifiés à partir de la pose au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore puisse résoudre une ancre cloud, bien que la précision de la pose résolue soit probablement réduite. Encouragez l'utilisateur à déplacer l'appareil afin que la position souhaitée de l'ancre cloud qu'il souhaite héberger puisse être vue sous différents angles.
GOOD La qualité des points d'intérêt identifiés à partir de la pose au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore puisse résoudre une ancre cloud avec un degré de précision élevé.

Résoudre une ancre précédemment hébergée

Appelez resolveCloudAnchorAsync() pour résoudre une ancre cloud hébergée. L'API ARCore compare régulièrement les caractéristiques visuelles de la scène à la carte de caractéristiques 3D de l'ancre pour indiquer la position et l'orientation de l'utilisateur par rapport à l'ancre. Lorsqu'une correspondance est trouvée, l'API renvoie la pose de l'ancre Cloud hébergée.

Vous pouvez lancer des résolutions pour plusieurs ancres cloud dans l'ordre. Vous pouvez exécuter jusqu'à 40 opérations d'ancrage cloud simultanées.

Annuler une opération ou supprimer une ancre cloud

Appelez cancel() pour annuler une opération d'ancrage cloud en attente. Appelez detach() pour supprimer une ancre cloud déjà résolue de l'application.

Vérifier l'état des résultats d'une opération Cloud Anchor

Utilisez Anchor.CloudAnchorState pour vérifier l'état du résultat de l'opération d'hébergement ou de résolution, y compris les erreurs.

Valeur Description
ERROR_CLOUD_ID_NOT_FOUND La résolution a échoué, car l'API ARCore n'a pas trouvé l'ID d'ancre cloud fourni.
ERROR_HOSTING_DATASET_PROCESSING_FAILED L'hébergement a échoué, car le serveur n'a pas réussi à traiter l'ensemble de données pour l'ancre donnée. Réessayez une fois que l'appareil a collecté davantage de données dans l'environnement.
ERROR_HOSTING_SERVICE_UNAVAILABLE L'API ARCore était inaccessible. Ce problème peut avoir plusieurs causes. L'appareil est peut-être en mode Avion ou ne dispose pas d'une connexion Internet fonctionnelle. Le délai de la requête envoyée au serveur a peut-être expiré sans réponse. Il peut s'agir d'une mauvaise connexion réseau, d'une indisponibilité du DNS, de problèmes de pare-feu ou de tout autre élément pouvant affecter la capacité de l'appareil à se connecter à l'API ARCore.
ERROR_INTERNAL Une tâche d'hébergement ou de résolution de cet ancrage s'est terminée avec une erreur interne. L'application ne doit pas tenter de récupérer cette erreur.
ERROR_NOT_AUTHORIZED L'autorisation fournie par l'application n'est pas valide. Consultez Résoudre les problèmes d'autorisation de l'API ARCore.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW L'ancre cloud n'a pas pu être résolue, car la version du SDK utilisée pour la résoudre est plus récente que la version utilisée pour l'héberger et est incompatible avec elle.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Impossible de résoudre l'ancre cloud, car la version du SDK utilisée pour résoudre l'ancre est plus ancienne et incompatible avec la version utilisée pour l'héberger.
ERROR_RESOURCE_EXHAUSTED L'application a épuisé le quota de requêtes alloué au projet Google Cloud donné. Vous devez demander des quotas supplémentaires pour l'API ARCore pour votre projet dans la Google Developers Console.
SUCCESS Une tâche d'hébergement ou de résolution pour cette ancre a bien été effectuée.

Quotas d'API pour les requêtes d'hôte et de résolution

L'API ARCore applique les quotas de bande passante de requête suivants:

Type de quota Maximum Durée Applicable à
Nombre d'ancres illimité N/A projet
Requêtes host ancrées 30 minute Adresse IP et projet
Demandes d'résolution des ancres 300 minute Adresse IP et projet

Bonnes pratiques pour une bonne expérience utilisateur

Pour garantir une bonne expérience utilisateur sur votre application, demandez aux utilisateurs de procéder comme suit:

  • Attendez quelques secondes après le début de la session avant d'essayer d'héberger une ancre (en plaçant un objet, par exemple). Cela permet au suivi de se stabiliser.
  • Lorsque vous sélectionnez un emplacement pour héberger l'ancre, essayez de trouver une zone dont les caractéristiques visuelles sont facilement distinguables les unes des autres. Pour de meilleurs résultats, évitez les surfaces réfléchisantes ou celles qui ne présentent pas de caractéristiques visuelles, comme les murs blancs.

  • Maintenez l'entraînement de la caméra sur le centre d'intérêt et déplacez-le autour de ce centre d'intérêt pour cartographier l'environnement sous différents angles, en conservant à peu près la même distance physique. Cela permettra de capturer des données plus visuelles et d'améliorer la résolution.

  • Assurez-vous que l'environnement réel est suffisamment éclairé lorsque vous hébergez et résolvez des Cloud Anchors.

Règlement d'obsolescence

  • Les applications créées avec le SDK ARCore 1.12.0 ou version ultérieure sont couvertes par le Règlement d'abandon de l'API Cloud Anchor.
  • Les applications développées avec le SDK 1.11.0 ou version antérieure ARCore ne peuvent pas héberger ni résoudre des ancres cloud, car le SDK utilise une API ARCore plus ancienne et obsolète.

Étapes suivantes