Activer l'API Geospatial pour votre application Android (Kotlin/Java)

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

Prérequis

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

Application exemple et atelier de programmation

Cette vidéo explique les étapes à suivre pour créer une application qui affiche des données géospatiales et place du contenu dans des lieux réels à l'aide de l'API Geospatial.

Vous pouvez également suivre la documentation de l'atelier de programmation géospatiale pour suivre les mêmes étapes. Pour exécuter l'application exemple créée dans la vidéo, consultez le guide de démarrage rapide ARCore Geospatial.

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

Si vous débutez avec ARCore, consultez la page Premiers pas pour en savoir plus sur les exigences logicielles et matérielles, 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 la procédure de démarrage rapide.

Activer l'API ARCore

Avant d'utiliser le système de positionnement visuel (VPS) dans votre application, vous devez activer l'API ARCore dans un projet Google Cloud nouveau ou existant. Ce service est chargé d'héberger, de stocker et de résoudre les ancrages géospatiaux.

L'autorisation sans clé est recommandée, mais l'autorisation par clé API est également acceptée.

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 dans la configuration de la session par ENABLED:

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

Lorsque le mode géospatial est défini sur ENABLED, l'application est autorisée à obtenir des informations géographiques à partir du système VPS (Visual Positioning System).

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

Les applications qui utilisent l'API ARCore Geospatial doivent présenter à l'utilisateur une invite pour qu'il confirme et autorise l'utilisation des données de son appareil. Pour en savoir plus, consultez la section Exigences concernant la confidentialité des utilisateurs.

Vérifier la compatibilité de l'appareil

Tous les appareils compatibles avec ARCore ne sont pas compatibles avec l'API Geospatial, comme décrit dans le guide de démarrage.

Pour vérifier la compatibilité de l'appareil de l'utilisateur, appelez Session.checkGeospatialModeSupported(). Si cette valeur renvoie la valeur "false", n'essayez pas de configurer la session (ci-dessous), car une exception UnsupportedConfigurationException sera générée.

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

Votre application doit demander des autorisations 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 non précise la position de l'utilisateur et respecter les exigences de confidentialité des utilisateurs. Toutefois, l'API Geospatial ne peut pas être configurée pour fonctionner avec des données de localisation approximatives. 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 que votre application n'ait accès qu'aux informations de localisation approximatives. Pour répondre à cette requête, l'autorisation ACCESS_COARSE_LOCATION doit être configurée pour 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 précise dont elle a besoin. Le service Geospatial ne peut pas être configuré si votre application ne lui fournit qu'une position approximative. Votre application ne peut pas utiliser l'API Geospatial avec une position approximative.

Vérifier la disponibilité des services géospatiaux à l'emplacement actuel de l'appareil

Étant donné que l'API Geospatial utilise une combinaison de VPS et de GPS pour déterminer une pose géospatiale, elle peut être utilisée 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'appuie sur la couverture VPS pour générer des postures avec une grande précision. Dans des conditions normales, le VPS peut fournir une précision de position d'environ 5 mètres et une précision de rotation de 5 degrés. Utilisez Session.checkVpsAvailabilityAsync() pour déterminer si un emplacement donné est couvert par le VPS.

L'API Geospatial peut également être utilisée dans les zones non couvertes par le VPS. Dans les environnements extérieurs avec peu ou pas d'obstacles au-dessus, le GPS peut suffire à générer une pose avec une grande précision.

Étape suivante