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

  • Assurez-vous de bien comprendre le fonctionnement des ancrages et des ancrages 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 ARCore Cloud Anchor Management.

Votre application doit suivre ces étapes pour terminer l'hébergement d'une ancre cloud:

  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éter le code d'erreur en cas d'échec.
  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 caractéristiques de meilleure qualité sont généralement résolues avec plus de précision. 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 de caractéristiques identifiés à partir de la position au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore réussisse à résoudre une ancre cloud, même si la précision de la pose résolue sera 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 de caractéristiques identifiés à partir de la position au cours des quelques secondes précédentes est probablement suffisante pour qu'ARCore réussisse à résoudre une ancre cloud avec un haut degré de précision.

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 éléments visuels de la scène avec la carte des éléments 3D de l'ancrage pour déterminer la position et l'orientation de l'utilisateur par rapport à l'ancrage. 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 à la fois.

Annuler une opération ou supprimer un Cloud Anchor

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 du résultat d'une opération d'ancre cloud

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 Échec de la résolution, 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 lorsque l'appareil aura collecté davantage de données dans l'environnement.
ERROR_HOSTING_SERVICE_UNAVAILABLE Impossible d'accéder à l'API ARCore. 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 pour cette ancre 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 L'ancre cloud n'a pas pu être résolue, car la version du SDK utilisée pour la résoudre est antérieure à la version utilisée pour l'héberger et incompatible avec elle.
ERROR_RESOURCE_EXHAUSTED L'application a utilisé la totalité du 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 dispose des quotas suivants pour la bande passante des requêtes:

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

Bonnes pratiques pour une bonne expérience utilisateur

Demandez aux utilisateurs de suivre les instructions suivantes pour garantir une bonne expérience utilisateur dans votre application :

  • Attendez quelques secondes après le démarrage de la session avant de tenter d'héberger une ancre (en plaçant un objet, etc.). 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échissantes ou dépourvues d'éléments visuels, comme des murs blancs et blancs.

  • Maintenez la caméra entraînée sur le centre d'intérêt et déplacez l'appareil centre d'intérêt afin de cartographier l'environnement sous différents angles, en conservant à peu près la même distance physique que vous le faites. Cela vous aidera à capturer des données plus visuelles et à rendre la résolution plus robuste.

  • Assurez-vous que l'éclairage est suffisant en environnement réel lors de l'hébergement et de la résolution des ancres cloud.

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