Korzystanie z interfejsu ARCore API w Google Cloud

Wybierz platformę:

Funkcje ARCore, takie jak Geospatial API i Cloud Anchors, używają interfejsu ARCore API hostowanego w Google Cloud. Podczas korzystania z tych funkcji aplikacja używa danych logowania, aby uzyskać dostęp do usługi ARCore API.

Z tego krótkiego wprowadzenia dowiesz się, jak skonfigurować aplikację, aby komunikować się z usługą interfejsu ARCore API hostowaną w Google Cloud.

Utwórz nowy projekt Google Cloud lub użyj istniejącego projektu

Jeśli masz już projekt, wybierz go.

Otwórz selektor projektów

Jeśli nie masz żadnego projektu Google Cloud, utwórz go.

Utwórz nowy projekt

Włącz interfejs ARCore API

Aby używać interfejsu ARCore API, musisz włączyć go w swoim projekcie.

Włączanie interfejsu ARCore API

Skonfiguruj metodę autoryzacji

Aplikacja na Unity może komunikować się z interfejsem ARCore API za pomocą 2 różnych metod autoryzacji: autoryzacji bez klucza (zalecanej) oraz autoryzacji klucza interfejsu API:

  • Na Androidzie autoryzacja bezkluczykowa wykorzystuje kombinację nazwy pakietu aplikacji i odcisku cyfrowego klucza podpisywania, aby autoryzować aplikację.

    W systemie iOS autoryzacja bez kluczaająca korzysta z podpisanego tokena, aby kontrolować dostęp do interfejsu API. Ta metoda wymaga serwera, który należy do Ciebie, do podpisywania tokenów i kontrolowania dostępu do interfejsu API.

  • Klucz interfejsu API to ciąg znaków identyfikujący projekt Google Cloud. Klucze interfejsu API zwykle nie są uważane za bezpieczne, ponieważ zwykle są dostępne dla klientów. Do komunikacji z interfejsem ARCore API rozważ użycie autoryzacji bez klucza.

Bez klucza

Aby autoryzować aplikację za pomocą uwierzytelniania bez klucza, utwórz identyfikatory klienta OAuth 2.0.

Określanie odcisków cyfrowych klucza podpisywania

Identyfikator klienta OAuth 2.0 identyfikuje aplikację za pomocą odcisku cyfrowego klucza podpisywania aplikacji.

Jak uzyskać odcisk cyfrowy podpisu do debugowania

Podczas uruchamiania lub debugowania projektu narzędzia Android SDK automatycznie podpisują aplikację wygenerowanym certyfikatem debugowania.

Aby uzyskać odcisk cyfrowy certyfikatu debugowania, użyj poniższego polecenia.

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

Narzędzie keytool poprosi o wpisanie hasła do magazynu kluczy. Domyślne hasło magazynu kluczy debugowania to android. Następnie narzędzie keytool drukuje odcisk cyfrowy na terminalu. Na przykład:

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

Jak uzyskać odcisk cyfrowy podpisywania z magazynu kluczy

Jeśli masz plik magazynu kluczy, użyj narzędzia keytool, aby określić odcisk cyfrowy.

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

Następnie narzędzie keytool drukuje odcisk cyfrowy na terminalu. Na przykład:

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

Jak uzyskać klucz podpisywania aplikacji z usługi podpisywania aplikacji przez Google Play

Jeśli korzystasz z podpisywania aplikacji przez Google Play, Google zarządza kluczem podpisywania Twojej aplikacji i używa go do podpisywania plików APK. Ten klucz powinien być używany na potrzeby odcisku cyfrowego podpisywania.

  1. Na stronie podpisywania aplikacji w Konsoli Google Play przewiń do sekcji Certyfikat klucza podpisywania aplikacji.
  2. Użyj odcisku cyfrowego certyfikatu SHA-1.

Tworzenie identyfikatorów klienta OAuth 2.0

Dla każdego odpowiedniego klucza podpisywania z poprzednich kroków utwórz identyfikator klienta OAuth 2.0 w danych logowania do projektu Google Cloud.

  • W Google Cloud otwórz stronę Dane logowania.

    Dane logowania

  • Kliknij Utwórz dane logowania i w menu wybierz Identyfikator klienta OAuth.

  • Wypełnij wymagane pola w następujący sposób:

    • Typ aplikacji: wybierz Android.
    • Nazwa pakietu: użyj nazwy pakietu podanej w pliku AndroidManifest.xml.
    • Odcisk cyfrowy certyfikatu SHA-1: użyj odcisku cyfrowego uzyskanego w poprzednich krokach.

  • Kliknij Utwórz.

Dołącz wymagane biblioteki

  1. Dodaj com.google.android.gms:play-services-auth:16+ w zależnościach aplikacji.

  2. Jeśli używasz minifikacji kodu, dodaj go do pliku build.gradle aplikacji:

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

  3. Dodaj do pliku proguard-rules.pro aplikacji:

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

Twoja aplikacja jest teraz skonfigurowana do korzystania z uwierzytelniania bez klucza.

Bez klucza

ARCore obsługuje autoryzację wywołań interfejsu API w iOS przy użyciu (tokenu internetowego JSON). Token musi być podpisany za pomocą konta usługi Google.

Aby móc generować tokeny dla iOS, musisz mieć na serwerze punkt końcowy, który spełnia te wymagania:

  • Twój własny mechanizm autoryzacji musi chronić punkt końcowy.

  • Punkt końcowy musi za każdym razem wygenerować nowy token, na przykład:

    • Każdy użytkownik otrzymuje unikalny token.
    • Tokeny nie wygasają natychmiast.

Tworzenie konta usługi i klucza podpisywania

Aby utworzyć konto usługi Google i klucz podpisywania, wykonaj te czynności:

  1. W Google Cloud otwórz stronę Dane logowania.
    Dane logowania
  2. Kliknij Utwórz dane logowania > Konto usługi.
  3. W sekcji Szczegóły konta usługi wpisz nazwę nowego konta, a następnie kliknij Utwórz.
  4. Na stronie Uprawnienia konta usługi kliknij menu Wybierz rolę. Wybierz Konta usługi > Twórca tokenów konta usługi i kliknij Dalej.
  5. Na stronie Przyznaj użytkownikom dostęp do tego konta usługi kliknij Gotowe.
  6. Na stronie Dane logowania znajdź sekcję Konta usługi i kliknij nazwę utworzonego właśnie konta.
  7. Na stronie Szczegóły konta usługi przewiń w dół do sekcji Klucze i wybierz Dodaj klucz > Utwórz nowy klucz.

  8. Jako typ klucza wybierz JSON i kliknij Utwórz.

    Spowoduje to pobranie na Twój komputer pliku JSON z kluczem prywatnym. Zapisz pobrany plik klucza JSON w bezpiecznej lokalizacji.

Tworzenie tokenów na serwerze

Aby utworzyć nowe tokeny (JWT) na serwerze, użyj standardowych bibliotek JWT i pliku JSON pobranego bezpiecznie z nowego konta usługi.

Tworzenie tokenów na komputerze programisty

Aby wygenerować tokeny JWT na komputerze programisty, użyj tego polecenia oauth2l:

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

Określenie pustej lokalizacji pamięci podręcznej za pomocą flagi --cache jest konieczne, aby za każdym razem był generowany inny token. Pamiętaj, aby przyciąć wynikowy ciąg znaków. Dodatkowe spacje lub znaki nowego wiersza spowodują odrzucenie tokena przez interfejs API.

Podpisz token

Aby podpisać token JWT, musisz użyć algorytmu RS256 i następujących deklaracji:

  • iss – adres e-mail konta usługi.
  • sub – adres e-mail konta usługi.
  • iat – czas uniksowego wygenerowania tokena (w sekundach).
  • exp – iat + 3600 (1 godzina). Czas uniksowego wygaśnięcia tokena (w sekundach).
  • aud – grupa odbiorców. Musi mieć wartość https://arcore.googleapis.com/.

Niestandardowe deklaracje nie są wymagane w ładunku JWT, ale deklaracja uid może być przydatna do identyfikacji odpowiedniego użytkownika.

Jeśli generujesz tokeny JWT w inny sposób, na przykład za pomocą interfejsu Google API w środowisku zarządzanym przez Google, pamiętaj, aby podpisać tokeny JWT za pomocą deklaracji podanych w tej sekcji. Przede wszystkim upewnij się, że odbiorcy mają rację.

Przekaż token w sesji ARCore

  1. Sprawdź, czy Strategia uwierzytelniania w iOS jest ustawiona na UwierzytelnianieToken. W Unity kliknij Edit (Edytuj) > Project Settings (Ustawienia projektu) > XR Plug-in Management (Zarządzanie wtyczkami XR) > ARCore Extensions (Rozszerzenia ARCore). W menu Strategia uwierzytelniania iOS wybierz opcję Token uwierzytelniania.

  2. Gdy uzyskasz token, przekaż go do sesji ARCore za pomocą 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);

Twoja aplikacja jest teraz skonfigurowana do korzystania z uwierzytelniania bez klucza.

Przekażąc token do sesji, pamiętaj o tych kwestiach:

  • Jeśli do utworzenia sesji został użyty klucz interfejsu API, ARCore zignoruje token i zgłosi błąd.

    Jeśli nie potrzebujesz już klucza interfejsu API, usuń go w Konsoli Google Developers i usuń go z aplikacji.

  • ARCore ignoruje tokeny zawierające spacje lub znaki specjalne.

  • Tokeny tracą zwykle ważność po godzinie. Jeśli istnieje możliwość, że token wygaśnie podczas użycia, uzyskaj nowy token i przekaż go do interfejsu API.

Klucz interfejsu API

  1. W Google Cloud otwórz stronę Dane logowania.
    Dane logowania
  2. Kliknij Utwórz dane logowania i w menu wybierz Klucz interfejsu API.
    W oknie dialogowym utworzonego klucza interfejsu API pojawi się ciąg nowo utworzonego klucza.

  3. W Unity kliknij Edit (Edytuj) > Project Settings (Ustawienia projektu) > XR Plug-in Management (Zarządzanie wtyczkami XR) > ARCore Extensions (Rozszerzenia ARCore). Dla każdej platformy docelowej (Android, iOS) w menu Strategia uwierzytelniania wybierz opcję Klucz interfejsu API. Następnie wstaw klucz interfejsu API w odpowiednich polach.

  4. Zapoznaj się z dokumentacją dotyczącą ograniczeń klucza interfejsu API, aby zabezpieczyć swój klucz interfejsu API.

Twoja aplikacja jest teraz skonfigurowana do używania kluczy interfejsu API.

Co dalej

Po skonfigurowaniu autoryzacji sprawdź te funkcje ARCore, które z niej korzystają: