Configurare l'API Geospatial nella tua app

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
Occhiali XR con cavo
Audio e
occhiali con display
Scopri di più sui tipi di dispositivi XR →

Per utilizzare l'API Geospatial nella tua app, quest'ultima deve essere configurata per accedere all'API ARCore su Google Cloud. Questa API contiene il servizio di posizionamento visivo che fornisce un posizionamento preciso utilizzando i dati di Google Street View.

Questa guida ti aiuta a configurare un progetto Google Cloud in cui sono stati abilitati l'API e i metodi di autorizzazione corretti per accedere all'API.

Configura un progetto Google Cloud o utilizzane uno esistente

Se hai un progetto Google Cloud esistente, selezionalo.

Vai al selettore di progetti

Se non hai un progetto esistente, creane uno.

Crea un nuovo progetto

Abilita l'API ARCore

Per utilizzare l'API ARCore, devi abilitarla nel tuo progetto.

Abilita l'API ARCore

Configura l'autorizzazione per Google Cloud

Un'app per Android può comunicare con l'API ARCore utilizzando due diversi metodi di autorizzazione: l'autorizzazione senza chiave (OAuth 2.0), che è il metodo consigliato, e l'autorizzazione con chiave API:

  • L'autorizzazione senza chiave utilizza una combinazione del nome del pacchetto dell'applicazione e della fingerprint della chiave di firma per autorizzare l'applicazione.

  • Una chiave API è una stringa che identifica un progetto cloud di Google. Le chiavi API non sono generalmente considerate sicure, in quanto sono in genere accessibili ai client. Valuta la possibilità di utilizzare l'autorizzazione senza chiavi per comunicare con l'API ARCore.

Autorizzazione senza chiave

Per autorizzare la tua app utilizzando l'autenticazione keyless, crea ID client OAuth 2.0.

  1. In Google Cloud, vai alla pagina Credenziali.

    Vai a credenziali

  2. Fai clic su Crea credenziali, quindi seleziona ID client OAuth dal menu.

  3. Compila i campi obbligatori come segue:

    • Tipo di applicazione: scegli Android.
    • Nome del pacchetto: utilizza il nome del pacchetto dichiarato nel file AndroidManifest.xml.
    • Fingerprint del certificato SHA-1: ottieni le fingerprint del certificato SHA-1 seguendo le istruzioni riportate in Autenticazione client.

  4. Premi Crea.

Chiave API

Crea una chiave API dalla console Google Cloud seguendo questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Credenziali:

    Vai a credenziali

  2. Fai clic su Crea credenziali, quindi seleziona Chiave API dal menu.

  3. Aggiungi una restrizione API per l'API ARCore. Per saperne di più, consulta Applica le restrizioni delle chiavi API.

  4. Fai clic su Crea. La finestra di dialogo Chiave API creata mostra la stringa per la chiave appena creata.

In Android Studio, aggiungi la nuova chiave API al progetto. Includi la chiave API in un elemento <meta-data> nell'elemento <application> nel file AndroidManifest.xml dell'app:

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

Richiedi le autorizzazioni necessarie

Per utilizzare l'API Geospatial in ARCore con Jetpack XR, la tua app deve richiedere le seguenti autorizzazioni di runtime:

Sui dispositivi mobili, l'API Geospatial richiede anche le seguenti autorizzazioni:

Accedi a una sessione

Accedi alle informazioni geospaziali tramite un runtime Jetpack XR Session, che la tua app deve creare.

Configura la sessione

L'API Geospatial non è abilitata per impostazione predefinita nelle sessioni XR. L'app deve attivarlo esplicitamente configurando un GeospatialMode su Session. Sono disponibili le seguenti modalità:

  • GeospatialMode.SPATIAL: l'API Geospatial è abilitata. L'API Geospatial utilizza il Visual Positioning System (VPS), i dati del Global Positioning System (GPS) e i sensori di movimento del dispositivo per determinare la posizione geospaziale del dispositivo. Questa modalità non è disponibile sugli occhiali intelligenti.
  • GeospatialMode.INERTIAL: l'API Geospatial è attivata in modalità a basso consumo. L'API Geospatial utilizza solo il GPS e i sensori di movimento del dispositivo per determinare la posa geospaziale del dispositivo. Questa modalità è disponibile solo sugli occhiali intelligenti.
  • GeospatialMode.DISABLED: l'API Geospatial è disabilitata. Quando si passa da un'altra modalità a questa, l'API Geospatial rilascia tutte le risorse acquisite e interrompe il monitoraggio.

Non tutti i dispositivi supportano tutte le modalità Geospatial. Per saperne di più, consulta GeospatialMode. Utilizza XrDevice.isGeospatialSupported per verificare se un determinato GeospatialMode è supportato.

Il seguente esempio di codice mostra come impostare un GeospatialMode utilizzando 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.
}

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

Le app che utilizzano l'API Geospatial con ARCore per Jetpack XR devono mostrare all'utente un prompt per confermare e consentire l'utilizzo dei dati del suo dispositivo. Per saperne di più, consulta i requisiti di privacy dell'utente.

Utilizza l'oggetto Geospatial

Una volta configurata la sessione, ottieni l'oggetto Geospatial utilizzando Geospatial.getInstance. Utilizza l'oggetto Geospatial solo quando il suo stato è GeospatialTrackingState.RUNNING.

I seguenti esempi di codice mostrano come monitorare lo stato di Geospatial utilizzando 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.
        }
    }
}

Informazioni sui valori di accuratezza

Quando l'API Geospatial è abilitata, fornisce tre valori di accuratezza: orizzontale, verticale e di orientamento. Questi valori di accuratezza vengono aggiornati nel tempo e possono essere resi più precisi man mano che vengono acquisiti più dati. Valori più grandi indicano un'accuratezza inferiore e sono definiti come il raggio di un livello di confidenza del 68%. In altre parole, esiste una probabilità del 68% che il valore reale rientri nel raggio specificato del valore stimato.

Utilizza Geospatial.State.horizontalAccuracy, verticalAccuracy e orientationYawAccuracy per ottenere i valori di accuratezza attuali.

La tua app potrebbe richiedere un livello di precisione specifico per funzionare correttamente. Ad esempio, l'app potrebbe voler attendere che l'accuratezza orizzontale sia inferiore a 5 metri prima di eseguire il rendering dei contenuti virtuali. Per aumentare la probabilità di ottenere dati di maggiore precisione, l'app deve invitare gli utenti a guardarsi intorno, preferibilmente verso edifici o altri elementi con dettagli visivi elevati presenti in Google Street View. Utilizza Geospatial.checkVpsAvailability per determinare se il VPS è disponibile nella località specificata.

Passaggi successivi

Se l'API Geospatial è configurata correttamente, la tua app può: