Activer l'API Geospatial pour votre application NDK Android (C)

Configurez les paramètres de votre application afin qu'elle puisse utiliser l'API Geospatial.

Prérequis

Assurez-vous de bien comprendre les concepts fondamentaux de la RA et de configurer une session ARCore avant de continuer.

Si vous souhaitez exécuter un exemple d'application illustrant la fonctionnalité décrite ici, consultez le guide de démarrage rapide de ARCore Geospatial pour Android pour Java. L'exemple d'application présenté dans le guide de démarrage rapide est écrit en Java. Les exemples de code de ce document concernent la même fonctionnalité écrite en C.

Pour en savoir plus sur l'API Geospatial, consultez la page Présentation de l'API Geospatial.

Si vous débutez dans le développement avec ARCore, consultez la page Premiers pas pour en savoir plus sur la configuration logicielle et matérielle requise, les conditions préalables et d'autres informations spécifiques aux plates-formes que vous utilisez.

Assurez-vous que votre environnement de développement répond aux exigences du SDK ARCore, comme décrit dans le guide de démarrage rapide pour Java.

Activer l'API ARCore

Avant d'utiliser le système de positionnement visuel (VPS) dans votre application, vous devez d'abord activer l'API ARCore dans un projet Google Cloud nouveau ou existant. Ce service est responsable de l'hébergement, du stockage et de la résolution des ancres géospatiales.

L'autorisation sans clé est préférable, mais l'autorisation par clé API est également prise en charge.

Ajouter les bibliothèques requises à votre application

Après avoir autorisé votre application à appeler l'API ARCore, vous devez ajouter des bibliothèques pour activer les fonctionnalités géospatiales dans votre application.

Dans le fichier build.gradle de votre application, configurez les services Google Play pour inclure la bibliothèque de localisation des services Play.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

Activer les fonctionnalités géospatiales dans la configuration de la session

Avant de créer la session, remplacez GeospatialMode par ENABLED dans la configuration de votre session:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

Lorsque le mode Geospatial est défini sur ENABLED, l'application est autorisée à obtenir des informations géographiques à partir du système de positionnement visuel (VPS).

Inviter l'utilisateur à autoriser l'utilisation des données de l'appareil

Les applications qui utilisent l'API ARCore Geospatial doivent présenter à l'utilisateur un message l'invitant à accuser réception du message et à autoriser l'utilisation des données de son appareil. Pour en savoir plus, consultez les Exigences concernant la confidentialité des utilisateurs.

Vérifier la compatibilité de l'appareil

Les appareils compatibles avec ARCore ne sont pas tous compatibles avec l'API Geospatial, comme décrit dans le quickstart pour Java.

Pour vérifier la compatibilité de l'appareil de l'utilisateur, appelez ArSession_isGeospatialModeSupported(). Si la valeur "false" est renvoyée, n'essayez pas de configurer la session (ci-dessous), car ArStatus renverrait une exception AR_ERROR_UNSUPPORTED_CONFIGURATION.

Demander à l'utilisateur l'autorisation d'accéder à la position au moment de l'exécution

Votre application doit demander l'autorisation d'accéder à la position au moment de l'exécution.

Pour utiliser l'API ARCore Geospatial, votre application doit enregistrer les autorisations supplémentaires suivantes:

  • ACCESS_FINE_LOCATION pour déterminer précisément la position de l'utilisateur

  • ACCESS_COARSE_LOCATION pour déterminer de manière incorrecte la position de l'utilisateur et pour respecter les exigences de confidentialité des utilisateurs. Toutefois, l'API Geospatial ne peut pas être configurée pour fonctionner avec une position approximative. Les requêtes API échouent lorsque l'utilisateur a défini cette autorisation. Pour en savoir plus, consultez les informations ci-dessous.

  • ACCESS_INTERNET pour contacter le service de l'API ARCore Geospatial.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Sur les appareils équipés d'Android 12 ou version ultérieure, les utilisateurs peuvent demander à votre application d'accéder uniquement aux informations de localisation approximatives. Pour répondre à cette requête, l'autorisation ACCESS_COARSE_LOCATION doit être configurée sur votre application, ainsi que ACCESS_FINE_LOCATION, comme indiqué ci-dessus. Vous devez configurer les deux autorisations d'accéder à la position.

Toutefois, lorsque les utilisateurs spécifient une position approximative, cela empêche l'API Geospatial d'obtenir la position exacte dont elle a besoin. Le service Geospatial ne peut pas être configuré si votre application ne lui fournit que la position approximative. Votre application ne peut pas utiliser l'API Geospatial avec la position approximative.

Vérifier la disponibilité géospatiale à la position actuelle de l'appareil

Étant donné que l'API Geospatial utilise une combinaison de VPS et de GPS pour déterminer une position géospatiale, vous pouvez l'utiliser tant que l'appareil est en mesure de déterminer sa position. Dans les zones où la précision du GPS est faible, comme les espaces intérieurs et les environnements urbains denses, l'API s'appuiera sur la couverture VPS pour générer des postures de haute précision. Dans des conditions classiques, on s'attend à ce que la précision de la position VPS soit d'environ 5 mètres et la précision de rotation de 5 degrés. Utilisez ArSession_checkVpsAvailabilityAsync() pour déterminer si un lieu donné est couvert par le service VPS.

L'API Geospatial peut également être utilisée dans les zones qui ne sont pas couvertes par un service VPS. Dans les environnements extérieurs avec peu ou pas d'obstacles au-dessus de la tête, le GPS peut suffire à prendre une pose avec une grande précision.

Étapes suivantes