Utilizzare l'API ARCore su Google Cloud

Seleziona la piattaforma:

Le funzionalità di ARCore, come l'API Geospaziale e Cloud Anchors, utilizzano l'API ARCore ospitata su Google Cloud. Quando utilizzi queste funzionalità, la tua applicazione utilizza le credenziali per accedere al servizio API ARCore.

Questa guida rapida descrive come configurare l'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 un progetto esistente, selezionalo.

Vai al selettore di progetti

Se non hai un progetto Google Cloud esistente, creane uno.

Crea nuovo progetto

Attivare l'API ARCore

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

Abilita l'API ARCore

Configurare un metodo di autorizzazione

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

  • Su Android, l'autorizzazione senza chiave utilizza una combinazione del nome del pacchetto dell'applicazione e dell'impronta 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 un server di tua proprietà per firmare i token e controllare l'accesso all'API.

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

Keyless

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

Determinare le impronte delle chiavi di firma

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

Come ottenere l'impronta della firma di debug

Quando esegui o esegui il debug del progetto, gli strumenti SDK Android firmano automaticamente la tua app con un certificato di debug generato.

Utilizza il seguente comando per ottenere il fingerprint 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 ti chiede di inserire una password per l'archivio chiavi. La password predefinita per l'archivio chiavi di debug è android. L'utilità keytool stampa l'impronta nel 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 un'impronta di firma da un keystore

Se hai un file keystore, utilizza l'utilità keytool per determinare l'impronta.

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

L'utilità keytool stampa quindi 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

Quando 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 della 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: utilizza un fingerprint ottenuto nei passaggi precedenti.

  • Premi Crea.

Includere le librerie richieste

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

  2. Se utilizzi la riduzione del codice, aggiungila al file build.gradle della tua app:

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

  3. Aggiungi quanto segue 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.** { *; }

La tua app è ora configurata per utilizzare l'autenticazione senza chiave.

Keyless

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 tuo meccanismo di autorizzazione deve proteggere l'endpoint.

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

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

Creare un service account e una chiave di firma

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

  1. In Google Cloud, apri la pagina Credenziali.
    Credenziali
  2. Fai clic su Crea credenziali > Service account.
  3. In Dettagli service account, digita un nome per il nuovo account, quindi fai clic su Crea.
  4. Nella pagina Autorizzazioni service account, 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 service account, fai clic su Fine.
  6. Nella pagina Credenziali, individua la sezione Account di servizio e fai clic sul nome dell'account che hai appena creato.
  7. Nella pagina Dettagli service account, 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.

    Viene scaricato un file JSON contenente la chiave privata sul computer. Archivia il file della chiave JSON scaricato in una posizione sicura.

Crea token sul server

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

Crea token sulla macchina di sviluppo

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

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

La specifica di una posizione della cache vuota utilizzando il flag --cache è necessaria per garantire che venga prodotto un token diverso ogni volta. Assicurati di tagliare la stringa risultante. Spazi aggiuntivi o caratteri di nuova riga faranno sì che l'API rifiuti il token.

Firma il token

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

  • iss: l'indirizzo email del service account.
  • sub: l'indirizzo email del service account.
  • iat: l'ora Unix epoch in cui è stato generato il token, in secondi.
  • exp - iat + 3600 (1 ora). L'ora Unix epoch in cui il token scade, in secondi.
  • aud: il pubblico. Deve essere impostato su https://arcore.googleapis.com/.

Le attestazioni non standard non sono richieste nel payload JWT, anche se l'attestazione uid può essere 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 rivendicazioni in questa sezione. Innanzitutto, assicurati che il pubblico sia corretto.

Passa il token nella sessione ARCore

  1. Assicurati che la strategia di autenticazione iOS sia impostata su AuthenticationToken. In Unity, vai a Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Nel menu a discesa Strategia di autenticazione iOS, seleziona l'opzione Token di autenticazione.

  2. Quando ottieni un token, passalo alla 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);

La tua app è ora configurata per utilizzare l'autenticazione senza chiave.

Tieni presente quanto segue quando passi un token nella sessione:

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

    Se non hai più bisogno della chiave API, eliminala in Google Developers Console e rimuovila dalla tua app.

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

  • I token scadono in genere dopo un'ora. Se esiste la possibilità che il token scada durante l'utilizzo, 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, poi seleziona Chiave API dal menu.
    La finestra di dialogo Chiave API creata mostra la stringa della chiave appena creata.

  3. In Unity, vai a Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Per ogni piattaforma di destinazione (Android, iOS), seleziona l'opzione Chiave API nel menu a discesa Strategia di autenticazione. Poi, inserisci la chiave API nei campi della chiave API.

  4. Consulta la documentazione sulle limitazioni 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, dai un'occhiata alle seguenti funzionalità di ARCore che la utilizzano: