ARCore API in Google Cloud verwenden

Plattform auswählen:

ARCore-Funktionen wie die Geospatial API und Cloud Anchors verwenden die in Google Cloud gehostete ARCore API. Wenn Sie diese Funktionen verwenden, greift Ihre Anwendung mit Anmeldedaten auf den ARCore API-Dienst zu.

In dieser Kurzanleitung wird beschrieben, wie Sie Ihre Anwendung so einrichten, dass sie mit dem in Google Cloud gehosteten ARCore API-Dienst kommunizieren kann.

Ein neues Google Cloud-Projekt erstellen oder ein vorhandenes Projekt verwenden

Wenn Sie ein vorhandenes Projekt haben, wählen Sie es aus.

Zur Projektauswahl

Wenn Sie noch kein Google Cloud-Projekt haben, erstellen Sie eines.

Neues Projekt erstellen

ARCore API aktivieren

Wenn Sie die ARCore API verwenden möchten, müssen Sie sie in Ihrem Projekt aktivieren.

ARCore API aktivieren

Autorisierungsmethode einrichten

Eine Unity-Anwendung kann über zwei verschiedene Autorisierungsmethoden mit der ARCore API kommunizieren: die schlüssellose Autorisierung (empfohlene Methode) und die API-Schlüssel-Autorisierung:

  • Unter Android wird bei der schlüssellosen Autorisierung eine Kombination aus dem Paketnamen der Anwendung und dem Fingerabdruck des Signaturschlüssels verwendet, um Ihre Anwendung zu autorisieren.

    Unter iOS wird bei der schlüssellosen Autorisierung ein signiertes Token verwendet, um den Zugriff auf die API zu steuern. Für diese Methode ist ein Server erforderlich, der Ihnen gehört, um Tokens zu signieren und den Zugriff auf die API zu steuern.

  • Ein API-Schlüssel ist ein String, der ein Google Cloud-Projekt identifiziert. API-Schlüssel gelten generell nicht als sicher, da sie normalerweise für Clients zugänglich sind. Erwägen Sie, die ARCore API ohne Schlüssel zu autorisieren.

Schlüssellose

Wenn Sie Ihre App mit der schlüssellosen Authentifizierung autorisieren möchten, erstellen Sie OAuth 2.0-Client-IDs.

Fingerabdrücke des Signaturschlüssels ermitteln

Eine OAuth 2.0-Client-ID verwendet den Fingerabdruck des Signaturschlüssels Ihrer App, um Ihre App zu identifizieren.

Release-Signierschlüssel.

Debug-Signatur-Fingerabdruck erhalten

Wenn Sie Ihr Projekt ausführen oder debuggen, signieren die Android SDK-Tools Ihre App automatisch mit einem generierten Debug-Zertifikat.

Verwenden Sie den folgenden Befehl, um den Fingerabdruck des Debug-Zertifikats abzurufen.

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

Das Dienstprogramm keytool fordert Sie auf, ein Passwort für den Schlüsselspeicher einzugeben. Das Standardschlüsselspeicherpasswort für die Fehlerbehebung ist android. Das Dienstprogramm keytool gibt den Fingerabdruck dann im Terminal aus. Beispiel:

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

Signatur-Fingerabdruck aus einem Keystore abrufen

Wenn Sie eine Keystore-Datei haben, verwenden Sie das keytool-Tool, um den Fingerabdruck zu ermitteln.

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

Das keytool-Tool gibt den Fingerabdruck dann im Terminal aus. Beispiel:

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

Signaturschlüssel Ihrer App über die Play App-Signatur abrufen

Wenn Sie die Play App-Signatur verwenden, verwaltet Google den Signaturschlüssel Ihrer App und verwendet ihn zum Signieren Ihrer APKs. Dieser Schlüssel sollte für den Signatur-Fingerabdruck verwendet werden.

  1. Scrollen Sie in der Google Play Console auf der Seite App-Signatur zu Zertifikat für App-Signaturschlüssel.
  2. Verwenden Sie den SHA-1-Zertifikat-Fingerabdruck.

OAuth 2.0-Client-IDs erstellen

Erstellen Sie für jeden entsprechenden Signierschlüssel aus den vorherigen Schritten eine OAuth 2.0-Client-ID in den Anmeldedaten Ihres Google Cloud-Projekts.

  • Öffnen Sie in Google Cloud die Seite „Anmeldedaten“.

    Anmeldedaten

  • Klicken Sie auf Anmeldedaten erstellen und wählen Sie im Menü OAuth-Client-ID aus.

  • Füllen Sie die Pflichtfelder so aus:

    • Anwendungstyp: Wählen Sie Android aus.
    • Paketname: Verwenden Sie den Paketnamen, der in Ihrer Datei AndroidManifest.xml deklariert ist.
    • SHA-1-Zertifikat-Fingerabdruck: Verwenden Sie einen Fingerabdruck, den Sie in vorherigen Schritten abgerufen haben.

  • Klicken Sie auf Erstellen.

Erforderliche Bibliotheken einbinden

  1. Fügen Sie com.google.android.gms:play-services-auth:16+ den Abhängigkeiten Ihrer App hinzu.

  2. Wenn Sie Code-Minifizierung verwenden, fügen Sie sie der Datei build.gradle Ihrer App hinzu:

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

  3. Fügen Sie der Datei proguard-rules.pro Ihrer App Folgendes hinzu:

    -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.** { *; }

Ihre App ist jetzt für die schlüssellose Authentifizierung konfiguriert.

Schlüssellose

ARCore unterstützt die Autorisierung von API-Aufrufen in iOS mithilfe eines JSON-Webtokens. Das Token muss von einem Google-Dienstkonto signiert werden.

Damit Sie Tokens für iOS generieren können, benötigen Sie einen Endpunkt auf Ihrem Server, der die folgenden Anforderungen erfüllt:

  • Der Endpunkt muss durch Ihren eigenen Autorisierungsmechanismus geschützt werden.

  • Der Endpunkt muss jedes Mal ein neues Token generieren, sodass:

    • Jeder Nutzer erhält ein eindeutiges Token.
    • Tokens laufen nicht sofort ab.

Dienstkonto und Signaturschlüssel erstellen

So erstellen Sie ein Google-Dienstkonto und einen Signaturschlüssel:

  1. Öffnen Sie in Google Cloud die Seite „Anmeldedaten“.
    Anmeldedaten
  2. Klicken Sie auf Anmeldedaten erstellen > Dienstkonto.
  3. Geben Sie unter Dienstkontodetails einen Namen für das neue Konto ein und klicken Sie dann auf Erstellen.
  4. Rufen Sie auf der Seite „Dienstkontoberechtigungen“ das Drop-down-Menü Rolle auswählen auf. Wählen Sie Dienstkonten > Ersteller von Dienstkonto-Tokens aus und klicken Sie auf „Weiter“.
  5. Klicken Sie auf der Seite Nutzern Zugriff auf dieses Dienstkonto erteilen auf „Fertig“.
  6. Suchen Sie auf der Seite Anmeldedaten nach dem Abschnitt „Dienstkonten“ und klicken Sie auf den Namen des Kontos, das Sie gerade erstellt haben.
  7. Scrollen Sie auf der Seite Dienstkontodetails zum Abschnitt „Schlüssel“ und wählen Sie Schlüssel hinzufügen > Neuen Schlüssel erstellen aus.

  8. Wählen Sie als Schlüsseltyp JSON aus und klicken Sie auf Erstellen.

    Dadurch wird eine JSON-Datei mit dem privaten Schlüssel auf Ihren Computer heruntergeladen. Speichern Sie die heruntergeladene JSON-Schlüsseldatei an einem sicheren Ort.

Tokens auf Ihrem Server erstellen

Verwenden Sie zum Erstellen neuer Tokens (JWTs) auf Ihrem Server die Standard-JWT-Bibliotheken und die JSON-Datei, die Sie sicher von Ihrem neuen Dienstkonto heruntergeladen haben.

Tokens auf Ihrer Entwicklungsmaschine erstellen

Verwenden Sie den folgenden oauth2l-Befehl, um JWTs auf Ihrem Entwicklungscomputer zu generieren:

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

Wenn Sie mit dem Flag --cache einen leeren Cache-Speicherort angeben, wird jedes Mal ein anderes Token generiert. Achten Sie darauf, den resultierenden String zu kürzen. Zusätzliche Leerzeichen oder Zeilenumbrüche führen dazu, dass die API das Token ablehnt.

Token signieren

Sie müssen den RS256-Algorithmus und die folgenden Ansprüche verwenden, um das JWT zu signieren:

  • iss: Die E-Mail-Adresse des Dienstkontos.
  • sub: Die E-Mail-Adresse des Dienstkontos.
  • iat: Die Unix-Epochenzeit, zu der das Token generiert wurde, in Sekunden.
  • exp – iat + 3600 (1 Stunde). Die Unix-Epochenzeit, zu der das Token abläuft, in Sekunden.
  • aud – Die Zielgruppe. Es muss auf https://arcore.googleapis.com/ gesetzt sein.

Nicht standardmäßige Anforderungen sind in der JWT-Nutzlast nicht erforderlich. Die Anforderung uid kann jedoch nützlich sein, um den entsprechenden Nutzer zu identifizieren.

Wenn Sie Ihre JWTs auf andere Weise generieren, z. B. mit einer Google API in einer von Google verwalteten Umgebung, müssen Sie Ihre JWTs mit den Anforderungen in diesem Abschnitt signieren. Achten Sie vor allem darauf, dass die Zielgruppe stimmt.

Token in der ARCore-Sitzung übergeben

  1. Prüfen Sie, ob die iOS Authentication Strategy auf AuthenticationToken festgelegt ist. Klicken Sie in Unity auf Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Wählen Sie im Drop-down-Menü iOS Authentication Strategy (iOS-Authentifizierungsstrategie) die Option Authentication Token (Authentifizierungstoken) aus.

  2. Wenn Sie ein Token erhalten, übergeben Sie es mit ARAnchorManager.SetAuthToken() an Ihre ARCore-Sitzung:

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

Ihre App ist jetzt für die schlüssellose Authentifizierung konfiguriert.

Beachten Sie beim Übergeben eines Tokens in die Sitzung Folgendes:

  • Wenn Sie einen API-Schlüssel zum Erstellen der Sitzung verwendet haben, ignoriert ARCore das Token und protokolliert einen Fehler.

    Wenn Sie den API-Schlüssel nicht mehr benötigen, löschen Sie ihn in der Google Developers Console und entfernen Sie ihn aus Ihrer App.

  • ARCore ignoriert Tokens, die Leerzeichen oder Sonderzeichen enthalten.

  • Tokens laufen in der Regel nach einer Stunde ab. Wenn Ihr Token während der Verwendung ablaufen kann, rufen Sie ein neues Token ab und übergeben Sie es an die API.

API-Schlüssel

  1. Öffnen Sie in Google Cloud die Seite „Anmeldedaten“.
    Anmeldedaten
  2. Klicken Sie auf Anmeldedaten erstellen und wählen Sie im Menü API-Schlüssel aus.
     Das Dialogfeld „API-Schlüssel erstellt“ enthält den String für den neu erstellten Schlüssel.

  3. Klicken Sie in Unity auf Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Wählen Sie für jede Zielplattform (Android, iOS) im Drop-down-Menü Authentifizierungsstrategie die Option API-Schlüssel aus. Fügen Sie dann Ihren API-Schlüssel in die API-Schlüsselfelder ein.

  4. Dokumentation zu API-Schlüsseleinschränkungen

Ihre App ist jetzt für die Verwendung von API-Schlüsseln konfiguriert.

Nächste Schritte

Nachdem Sie die Autorisierung konfiguriert haben, können Sie sich die folgenden ARCore-Funktionen ansehen, die sie verwenden: