Attiva l'API Geospatial per la tua app NDK per Android (C)

Configura le impostazioni dell'app in modo che possa utilizzare l'API Geospatial.

Prerequisiti

Prima di procedere, assicurati di conoscere i concetti fondamentali dell'AR e come configurare una sessione ARCore.

Se vuoi eseguire un'app di esempio che dimostri la funzionalità descritta qui, consulta la guida rapida ARCore Geospatial per Android per Java. L'app di esempio nella guida rapida è scritta in Java. Gli esempi di codice in questo documento si riferiscono alla stessa funzionalità scritta in C.

Per ulteriori informazioni sull'API Geospatial, consulta la Introduzione all'API Geospatial.

Se non hai mai sviluppato con ARCore, consulta la sezione Introduzione per informazioni sui requisiti hardware e software, sui prerequisiti e su altre informazioni specifiche per le piattaforme in uso.

Assicurati che l'ambiente di sviluppo soddisfi i requisiti dell'SDK ARCore, come descritto nella guida introduttiva per Java.

Attiva l'API ARCore

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

L'autorizzazione senza chiave è preferita, ma è supportata anche l'autorizzazione con chiave API.

Aggiungi le librerie richieste alla tua app

Dopo aver autorizzato la tua app a chiamare l'API ARCore, devi aggiungere librerie per attivare le funzionalità geospaziali nella tua app.

Nel file build.gradle dell'app, configura Google Play Services in modo da includere la raccolta Location di 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)'
}

Attivare le funzionalità geospaziali nella configurazione della sessione

Prima di creare la sessione, modifica GeospatialMode nella configurazione della sessione in ENABLED:

// 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);

Quando la modalità Geospaziale è impostata su ENABLED, l'applicazione è autorizzata a ottenere informazioni geografiche dal sistema di posizionamento visivo (VPS).

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

Le app che utilizzano l'API ARCore Geospatial devono presentare all'utente una richiesta di conferma e di autorizzazione all'utilizzo dei dati del suo dispositivo. Per ulteriori informazioni, consulta i requisiti relativi alla privacy dell'utente.

Verificare la compatibilità del dispositivo

Non tutti i dispositivi che supportano ARCore supportano anche l'API Geospatial, come descritto nella guida introduttiva per Java.

Per verificare la compatibilità del dispositivo dell'utente, chiama ArSession_isGeospatialModeSupported(). Se il valore restituito è false, non tentare di configurare la sessione (di seguito), poiché in questo modo ArStatus segnalerà un AR_ERROR_UNSUPPORTED_CONFIGURATION.

Chiedere all'utente le autorizzazioni di accesso alla posizione in fase di esecuzione

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

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

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

  • ACCESS_COARSE_LOCATION per la determinazione non accurata della posizione dell'utente e per rispettare i requisiti relativi alla privacy dell'utente. Tuttavia, l'API Geospatial non può essere configurata per funzionare con la posizione approssimativa e le richieste dell'API non andranno a buon fine se l'utente ha impostato questa autorizzazione. Per saperne di più, vedi di seguito.

  • ACCESS_INTERNET per contattare il servizio dell'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 versione 12 o successive, gli utenti possono richiedere che la tua app abbia accesso solo alle informazioni sulla posizione approssimativa. Per soddisfare questa richiesta, la tua app deve avere configurata l'autorizzazione ACCESS_COARSE_LOCATION insieme a ACCESS_FINE_LOCATION, come mostrato sopra. Devi configurare entrambe le autorizzazioni di accesso alla posizione.

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

Controllare la disponibilità geospaziale 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 determinare la propria posizione. Nelle aree con scarsa precisione del GPS, come spazi interni e ambienti urbani densi, l'API si baserà sulla copertura VPS per generare pose ad alta precisione. In condizioni normali, ci si aspetta che il servizio VPS fornisca una precisione di posizionamento di circa 5 metri e una precisione di rotazione di 5 gradi. Utilizza ArSession_checkVpsAvailabilityAsync() per determinare se una determinata località ha copertura VPS.

L'API Geospatial può essere utilizzata anche nelle aree che non hanno copertura VPS. In ambienti esterni con poche o nessuna ostruzione sopraelevata, il GPS potrebbe essere sufficiente per generare una posa con elevata precisione.

Passaggi successivi