Abilita l'API Geospatial per la tua app Android (Kotlin/Java)

Configura le impostazioni della tua app in modo che possa utilizzare l'API Geospaziale.

Prerequisiti

Assicurati di aver compreso i concetti fondamentali di AR e di configurare una sessione ARCore prima di procedere.

App e codelab di esempio

Questo video illustra i passaggi per la creazione di un'app che mostra dati geospaziali e posizioni i contenuti in località reali utilizzando l'API Geospatial.

Per gli stessi passaggi, puoi anche seguire la documentazione del codelab geospaziale. Per eseguire l'app di esempio creata nel video, consulta la guida rapida di ARCore Geospatial.

Consulta l'introduzione all'API Geospatial per ulteriori informazioni sull'API Geospatial.

Se è la prima volta che utilizzi ARCore, consulta la Guida introduttiva per informazioni su requisiti software e hardware, prerequisiti e altre informazioni specifiche per le piattaforme in uso.

Assicurati che il tuo ambiente di sviluppo soddisfi i requisiti dell'SDK ARCore, come descritto nella guida rapida.

Abilita l'API ARCore

Prima di utilizzare il sistema di posizionamento visivo (VPS) nell'app, devi abilitare l'API ARCore in un progetto Google Cloud nuovo o esistente. Questo servizio è responsabile dell'hosting, dell'archiviazione e della risoluzione degli ancoraggi geospaziali.

È preferibile l'autorizzazione senza chiave, ma è supportata anche l'autorizzazione tramite chiave API.

Aggiungi le librerie richieste alla tua app

Dopo aver autorizzato l'app a chiamare l'API ARCore, devi aggiungere librerie per abilitare le funzionalità geospaziali nell'app.

Nel file build.gradle dell'app, configura Google Play Services in modo da includere la libreria di località Play Services.

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)'
}

Attiva le funzionalità geospaziali nella configurazione della sessione

Prima di creare la sessione, modifica il GeospatialMode nella configurazione della sessione in 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 })

Mentre la modalità geospaziale è impostata su ENABLED, l'applicazione può ottenere informazioni geografiche dal sistema di posizionamento visivo (VPS).

Chiedi all'utente di consentire l'utilizzo dei dati del dispositivo

Le app che usano l'API ARCore Geospatial devono presentare all'utente una richiesta di conferma e di autorizzazione per l'utilizzo dei dati del dispositivo. Per ulteriori informazioni, consulta Requisiti per la privacy dell'utente.

Verificare la compatibilità del dispositivo

Non tutti i dispositivi che supportano ARCore supportano anche l'API Geospatial, come descritto nella quickstart.

Per verificare la compatibilità del dispositivo dell'utente, chiama il numero Session.checkGeospatialModeSupported(). Se restituisce false, non tentare di configurare la sessione (di seguito), poiché così facendo verrà generato un elemento UnsupportedConfigurationException.

Chiedi all'utente le autorizzazioni di accesso alla posizione in fase di runtime

L'app deve richiedere le autorizzazioni di accesso alla posizione in fase di runtime.

Per utilizzare l'API ARCore Geospatial, l'app deve registrare le seguenti autorizzazioni aggiuntive:

  • ACCESS_FINE_LOCATION per determinare con precisione la posizione dell'utente.

  • ACCESS_COARSE_LOCATION per una determinazione non accurata della località dell'utente e per rispettare i requisiti di privacy dell'utente. Tuttavia, non è possibile configurare l'API Geospatial per funzionare con la posizione approssimativa e le richieste API non andranno a buon fine quando l'utente avrà impostato questa autorizzazione. Per saperne di più, vedi di seguito.

  • ACCESS_INTERNET per contattare il servizio 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>

Sui dispositivi con Android 12 o versioni successive, gli utenti possono richiedere che la tua app abbia accesso solo alle informazioni sulla posizione approssimativa. Per soddisfare questa richiesta, nella tua app deve essere configurata l'autorizzazione ACCESS_COARSE_LOCATION, oltre a ACCESS_FINE_LOCATION, come mostrato sopra. Devi configurare entrambe le autorizzazioni di accesso alla posizione.

Tuttavia, quando gli utenti specificano la posizione approssimativa, questo impedisce all'API geospaziale di ottenere la posizione esatta richiesta. Il servizio geospaziale non potrà essere configurato se la tua app fornisce solo la posizione approssimativa. La tua app non può utilizzare l'API Geospatial con posizione approssimativa.

Controlla la disponibilità dei dati geospaziali nella posizione attuale del dispositivo

Poiché l'API Geospatial utilizza una combinazione di VPS e GPS per determinare una posa geospaziale, l'API può essere utilizzata purché il dispositivo sia in grado di determinarne la posizione. Nelle aree con scarsa precisione GPS, come spazi interni e ambienti urbani ad alta densità, l'API si affiderà alla copertura VPS per generare pose ad alta precisione. In condizioni tipiche, il VPS dovrebbe fornire una precisione di posizione di circa 5 metri e una precisione di rotazione di 5 gradi. Utilizza Session.checkVpsAvailabilityAsync() per stabilire se una determinata località ha una copertura VPS.

L'API Geospatial può essere utilizzata anche in aree che non dispongono di copertura VPS. In ambienti all'aperto con poche ostruzioni o nessuna ostruzione, il GPS può essere sufficiente per acquisire una posizione con precisione.

Passaggi successivi