Utilizzare l'API ARCore su Google Cloud

Seleziona la piattaforma:

Le funzionalità ARCore come l'API Geospatial e i Cloud Anchor utilizzano l'API ARCore ospitata su Google Cloud. Quando usi queste funzionalità, l'applicazione usa le credenziali per accedere al servizio API ARCore.

Questa guida rapida descrive come configurare la tua applicazione in modo che possa comunicare con il servizio API ARCore ospitato su Google Cloud.

Crea un nuovo progetto Google Cloud o utilizzane uno esistente

Se hai già un progetto, selezionalo.

Vai al selettore progetti

Se non hai ancora un progetto Google Cloud, 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 un metodo di autorizzazione

Un'applicazione Unity può comunicare con l'API ARCore utilizzando due diversi metodi di autorizzazione: autorizzazione senza chiave, che è il metodo consigliato, e autorizzazione chiave API:

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

    Su iOS, l'autorizzazione senza chiave utilizza un token firmato per controllare l'accesso all'API. Questo metodo richiede che un server di tua proprietà firmi i token e controlli l'accesso all'API.

  • Una chiave API è una stringa che identifica un progetto Google Cloud. Generalmente le chiavi API non sono considerate sicure poiché sono accessibili ai client. Potresti utilizzare l'autorizzazione senza chiave per comunicare con l'API ARCore.

Senza chiave

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

Determinare le fingerprint della chiave di firma

Un ID client OAuth 2.0 utilizza l'impronta della chiave di firma dell'app per identificare l'app.

Come ottenere l'impronta per la firma di debug

Durante l'esecuzione o il debug del progetto, gli strumenti SDK Android firmano automaticamente la tua app con un certificato di debug generato.

Utilizza il comando seguente per ottenere l'impronta digitale del certificato di debug.

Mac/Linux
keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
Windows
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

L'utilità keytool richiede di inserire una password per l'archivio chiavi. La password predefinita per l'archivio chiavi di debug è android. L'utilità keytool stampa quindi l'impronta sul terminale. Ad esempio:

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Come ottenere una fingerprint di firma da un archivio chiavi

Se hai un file di archivio chiavi, utilizza l'utilità keytool per determinare la fingerprint.

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

L'utilità keytool quindi stampa l'impronta sul terminale. Ad esempio:

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Come ottenere la chiave di firma dell'app dalla firma dell'app di Google Play

Se utilizzi la firma dell'app di Google Play, Google gestisce la chiave di firma dell'app e la utilizza per firmare gli APK. Questa chiave deve essere utilizzata per l'impronta digitale di firma.

  1. Nella pagina Firma dell'app di Google Play Console, scorri fino a Certificato della chiave di firma dell'app.
  2. Utilizza l'impronta digitale del certificato SHA-1.

Creare ID client OAuth 2.0

Per ogni chiave di firma applicabile dei passaggi precedenti, crea un ID client OAuth 2.0 nelle credenziali del tuo progetto Google Cloud.

  • In Google Cloud, apri la pagina Credenziali.

    Credenziali

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

  • 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: viene utilizzata un'impronta ottenuta nei passaggi precedenti.

  • Premi Crea.

Includi le librerie richieste

  1. Includi com.google.android.gms:play-services-auth:16+ nelle dipendenze dell'app.

  2. Se utilizzi la minimizzazione del codice, aggiungila al file build.gradle dell'app:

    buildTypes {
  release {
    ...
    proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
  }
}

  3. Aggiungi il seguente codice al file proguard-rules.pro dell'app:

    -keep class com.google.android.gms.common.** { *; }
-keep class com.google.android.gms.location.** { *; }
-keep class com.google.android.gms.auth.** { *; }
-keep class com.google.android.gms.tasks.** { *; }

Ora la tua app è configurata per utilizzare l'autenticazione senza chiave.

Senza chiave

ARCore supporta l'autorizzazione delle chiamate API in iOS utilizzando un token web JSON. Il token deve essere firmato da un account di servizio Google.

Per generare token per iOS, devi avere un endpoint sul server che soddisfi i seguenti requisiti:

  • Il meccanismo di autorizzazione deve proteggere l'endpoint.

  • L'endpoint deve generare ogni volta un nuovo token, in modo che:

    • Ogni utente riceve un token univoco.
    • I token non scadono immediatamente.

Crea un account di servizio e una chiave di firma

Segui questi passaggi per creare un account di servizio Google e una chiave di firma:

  1. In Google Cloud, apri la pagina Credenziali.
    Credenziali
  2. Fai clic su Crea credenziali > Account di servizio.
  3. In Dettagli account di servizio, digita un nome per il nuovo account e fai clic su Crea.
  4. Nella pagina Autorizzazioni account di servizio, vai al menu a discesa Seleziona un ruolo. Seleziona Account di servizio > Creatore token account di servizio, quindi fai clic su Continua.
  5. Nella pagina Concedi agli utenti l'accesso a questo account di servizio, fai clic su Fine.
  6. Nella pagina Credenziali, individua la sezione Account di servizio e fai clic sul nome dell'account appena creato.
  7. Nella pagina Dettagli account di servizio, scorri verso il basso fino alla sezione Chiavi e seleziona Aggiungi chiave > Crea nuova chiave.

  8. Seleziona JSON come tipo di chiave e fai clic su Crea.

    In questo modo viene scaricato un file JSON contenente la chiave privata sulla tua macchina. Archivia il file di chiave JSON scaricato in un luogo sicuro.

Creare token sul server

Per creare nuovi token (JWT) sul tuo server, utilizza le librerie JWT standard e il file JSON che hai scaricato in modo sicuro dal tuo nuovo account di servizio.

Crea token sulla tua macchina di sviluppo

Per generare JWT sulla tua macchina di sviluppo, utilizza il seguente comando oauth2l:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

È necessario specificare una posizione della cache vuota utilizzando il flag --cache per garantire che ogni volta venga generato un token diverso. Assicurati di tagliare la stringa risultante. Se sono presenti spazi o caratteri di nuova riga in eccesso, l'API rifiuterà il token.

Firma il token

Per firmare il JWT, devi utilizzare l'algoritmo RS256 e le seguenti attestazioni:

  • iss: l'indirizzo email dell'account di servizio.
  • sub: l'indirizzo email dell'account di servizio.
  • iat: data e ora di Unix in cui è stato generato il token, in secondi.
  • exp - iat + 3600 (1 ora). Il periodo di tempo di Unix in cui scade il token, in secondi.
  • aud: il pubblico. Deve essere impostato su https://arcore.googleapis.com/.

Le attestazioni non standard non sono necessarie nel payload JWT, ma la richiesta uid potrebbe risultare utile per identificare l'utente corrispondente.

Se utilizzi un approccio diverso per generare i JWT, ad esempio utilizzando un'API Google in un ambiente gestito da Google, assicurati di firmare i JWT con le attestazioni in questa sezione. Innanzitutto, assicurati che il pubblico sia corretto.

Passare il token nella sessione ARCore

  1. Assicurati che iOS Authentication Strategy (Strategia di autenticazione iOS) sia impostato su AuthenticationToken. In Unity, vai a Modifica > Impostazioni progetto > Gestione dei plug-in XR > Estensioni ARCore. Nel menu a discesa Strategia di autenticazione iOS, seleziona l'opzione Token di autenticazione.

  2. Quando ottieni un token, passalo alla tua sessione ARCore utilizzando ARAnchorManager.SetAuthToken():

    // Designate the token to authorize ARCore API calls
// on the iOS platform. This should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(authToken);

Ora la tua app è configurata per utilizzare l'autenticazione senza chiave.

Quando passi un token alla sessione, tieni presente quanto segue:

  • Se hai utilizzato una chiave API per creare la sessione, ARCore ignorerà il token e registrerà un errore.

    Se non ti serve più la chiave API, eliminala in Google Developers Console e rimuovila dall'app.

  • ARCore ignora i token che contengono spazi o caratteri speciali.

  • In genere i token scadono dopo un'ora. Se esiste la possibilità che il token scada durante l'uso, ottieni un nuovo token e passalo all'API.

Chiave API

  1. In Google Cloud, apri la pagina Credenziali.
    Credenziali
  2. Fai clic su Crea credenziali, quindi seleziona Chiave API dal menu.
    Nella finestra di dialogo della chiave API creata viene visualizzata la stringa per la chiave appena creata.

  3. In Unity, vai a Modifica > Impostazioni progetto > Gestione dei plug-in XR > Estensioni ARCore. Per ogni piattaforma di destinazione (Android, iOS), nel menu a discesa Strategia di autenticazione, seleziona l'opzione Chiave API. Poi, inserisci la chiave API nei campi Chiave API.

  4. Consulta la documentazione sulle restrizioni relative alle chiavi API per proteggere la tua chiave API.

Ora la tua app è configurata per utilizzare le chiavi API.

Passaggi successivi

Con l'autorizzazione configurata, controlla le seguenti funzionalità di ARCore che la utilizzano: