Pour utiliser l'API Geospatial dans votre application, celle-ci doit être configurée pour accéder à l'API ARCore sur Google Cloud. Cette API contient le service de positionnement visuel, qui fournit un positionnement précis à l'aide des données de Google Street View.
Ce guide vous aide à configurer un projet Google Cloud pour lequel l'API et les méthodes d'autorisation appropriées ont été activées pour accéder à l'API.
Configurer un projet Google Cloud ou utiliser un projet existant
Si vous avez déjà un projet Google Cloud, sélectionnez-le.
Accéder au sélecteur de projet
Si vous ne disposez d'aucun projet, créez-en un.
Activer l'API ARCore
Pour utiliser l'API ARCore, vous devez l'activer dans votre projet.
Configurer l'autorisation pour Google Cloud
Une application Android peut communiquer avec l'API ARCore à l'aide de deux méthodes d'autorisation différentes : l'autorisation sans clé (OAuth 2.0), qui est la méthode recommandée, et l'autorisation par clé API :
- L'autorisation sans clé utilise une combinaison du nom de package de l'application et de l'empreinte de la clé de signature pour autoriser votre application.
Une clé API est une chaîne qui identifie un projet Google Cloud. Les clés API ne sont généralement pas considérées comme sécurisées, car elles sont généralement accessibles aux clients. Envisagez d'utiliser l'autorisation sans clé pour communiquer avec l'API ARCore.
Autorisation sans clé
Pour autoriser votre application à l'aide de l'authentification sans clé, créez des ID client OAuth 2.0.
Dans Google Cloud, accédez à la page Identifiants.
Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth dans le menu.
Renseignez les champs obligatoires comme suit :
- Type d'application : sélectionnez Android.
- Nom du package : utilisez le nom du package tel qu'il est déclaré dans votre fichier
AndroidManifest.xml. - Empreinte du certificat SHA-1 : obtenez les empreintes du certificat SHA-1 en suivant les instructions de la section Authentification du client.
Appuyez sur Créer.
Clé API
Pour créer une clé API à partir de la console Google Cloud, procédez comme suit :
Dans la console Google Cloud, accédez à la page Identifiants.
Cliquez sur Créer des identifiants, puis sélectionnez Clé API dans le menu.
Ajoutez une restriction d'API pour l'API ARCore. Pour en savoir plus, consultez Appliquer des restrictions de clé API.
Cliquez sur Créer. La boîte de dialogue Clé API créée affiche la chaîne correspondant à la clé que vous venez de créer.
Dans Android Studio, ajoutez la nouvelle clé API à votre projet. Incluez la clé API dans un élément <meta-data> de l'élément <application> du fichier AndroidManifest.xml de votre application :
<meta-data
android:name="com.google.android.ar.API_KEY"
android:value="API_KEY"/>
Demander les autorisations requises
Pour utiliser l'API Geospatial dans ARCore avec Jetpack XR, votre application doit demander les autorisations d'exécution suivantes :
ACCESS_FINE_LOCATION: requis pour déterminer la position exacte d'un utilisateur.
Sur les appareils mobiles, l'API Geospatial nécessite également les autorisations suivantes :
android.permission.CAMERA: requis pour accéder à l'appareil photo de l' appareil.android.permission.INTERNET: requis pour communiquer avec les services Google Cloud.
Accéder à une session
Accédez aux informations géospatiales via un Session d'exécution Jetpack XR, que votre application doit créer.
Configurer la session
L'API Geospatial n'est pas activée par défaut sur les sessions XR. Votre application doit l'activer explicitement en configurant un GeospatialMode sur le Session. Les modes suivants sont disponibles :
GeospatialMode.SPATIAL: l'API Geospatial est activée. L'API Geospatial utilise le système de positionnement visuel (VPS), les données du système de positionnement global (GPS) et les capteurs de mouvement de l'appareil pour déterminer la position géospatiale de l'appareil. Ce mode n'est pas disponible sur les lunettes connectées.GeospatialMode.INERTIAL: l'API Geospatial est activée en mode basse consommation. L'API Geospatial n'utilise que le GPS et les capteurs de mouvement de l'appareil pour déterminer sa position géospatiale. Ce mode n'est disponible que sur les lunettes connectées.GeospatialMode.DISABLED: l'API Geospatial est désactivée. Lors du passage d'un autre mode à ce mode, l'API Geospatial libère toutes les ressources acquises et arrête le suivi.
Tous les appareils ne sont pas compatibles avec tous les modes géospatiaux. Pour en savoir plus, consultez GeospatialMode. Utilisez XrDevice.isGeospatialSupported pour déterminer si un GeospatialMode donné est compatible.
L'exemple de code suivant montre comment définir un GeospatialMode à l'aide de Session.configure.
// Define the configuration object to enable Geospatial features. val newConfig = Config.Builder(session.config) .setGeospatial(GeospatialMode.SPATIAL) .build() // Apply the configuration to the session. try { when (val configResult = session.configure(newConfig)) { is SessionConfigureSuccess -> { // The session is now configured to use the Geospatial API. } else -> { // Handle other configuration errors (e.g., missing library dependencies). } } } catch (e: UnsupportedOperationException) { // Handle configuration failure if the mode is not supported. }
Inviter l'utilisateur à autoriser l'utilisation des données de l'appareil
Les applications qui utilisent l'API Geospatial avec ARCore pour Jetpack XR doivent inviter l'utilisateur à accepter et à autoriser l'utilisation des données de son appareil. Pour en savoir plus, consultez les exigences de confidentialité des utilisateurs.
Utiliser l'objet Geospatial
Une fois la session configurée, obtenez l'objet Geospatial à l'aide de Geospatial.getInstance. N'utilisez l'objet Geospatial que lorsque son état est GeospatialTrackingState.RUNNING.
Les exemples de code suivants montrent comment surveiller l'état géospatial à l'aide de Geospatial.state.
Compose XR
val geospatial = remember { Geospatial.getInstance(session) } val geospatialState by geospatial.state.collectAsStateWithLifecycle() if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) { // Queries to the Geospatial API are only valid when the state is RUNNING. }
SceneCore
val geospatial = Geospatial.getInstance(session) lifecycleScope.launch { geospatial.state.collect { geospatialState -> if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) { // Queries to the Geospatial API are only valid when the state is RUNNING. } } }
Comprendre les valeurs de précision
Lorsque l'API Geospatial est activée, elle fournit trois valeurs de précision : la précision horizontale, la précision verticale et la précision de l'orientation. Ces valeurs de précision sont mises à jour au fil du temps et peuvent être affinées à mesure que des données sont acquises. Les valeurs plus élevées indiquent une précision plus faible et sont définies comme le rayon d'un niveau de confiance de 68 %. En d'autres termes, il y a 68 % de chances que la valeur réelle se trouve dans le rayon donné de la valeur estimée.
Utilisez Geospatial.State.horizontalAccuracy, verticalAccuracy et orientationYawAccuracy pour obtenir les valeurs de précision actuelles.
Votre application peut nécessiter un niveau de précision spécifique pour fonctionner correctement. Par exemple, votre application peut attendre que la précision horizontale soit inférieure à cinq mètres avant d'afficher du contenu virtuel. Pour augmenter la probabilité d'obtenir des données plus précises, votre application doit inviter les utilisateurs à regarder autour d'eux, de préférence les bâtiments ou d'autres éléments visuels très détaillés présents dans Google Street View. Utilisez Geospatial.checkVpsAvailability pour déterminer si le VPS est disponible à l'emplacement donné.
Étape suivante
Une fois l'API Geospatial correctement configurée dans votre application, celle-ci peut effectuer les opérations suivantes :
- Convertir des poses locales de l'appareil en poses géospatiales
- Afficher le contenu aux positions géospatiales