Przewodnik dla programistów Cloud Anchors na temat kierowania na Unity na iOS

Dowiedz się, jak używać zakotwiczeń w chmurze we własnych aplikacjach.

Wymagania wstępne

Zanim przejdziesz dalej, przeczytaj podstawowe zagadnienia dotyczące AR i skonfiguruj sesję ARCore.

Jeśli dopiero zaczynasz korzystać z zakotwiczeń w chmurze, upewnij się, że wiesz, jak działają kotwice i kotwiska Cloud.

Włączanie w aplikacji kotwicy w chmurze

Kotwice chmury są domyślnie wyłączone w ARCore. Przykładowa aplikacja jest dostarczana z włączonymi kotwicami Cloud. Zanim zaczniesz korzystać z kotwic Cloud w swojej aplikacji, musisz włączyć ARARCore API w nowym lub istniejącym projekcie Google Cloud Platform. Ta usługa odpowiada za hostowanie, przechowywanie i rozwiązywanie problemów z kotwicami Cloud.

Musisz też włączyć funkcje Cloud Anchor w konfiguracji sesji AR aplikacji, aby mogła ona komunikować się z interfejsem ARCore API:

  1. Włącz funkcje Cloud Anchor w konfiguracji sesji AR.
  2. Wznów sesję AR.

Uwierzytelnianie aplikacji za pomocą interfejsu ARCore API

Musisz uwierzytelnić interfejs ARCore API w aplikacji, aby hostować i rozwiązywać problemy z zakotwiczeniami w chmurze. Aplikacje, które hostują i usuwają kotwice Cloud z TTL przez więcej niż 1 dzień, muszą używać tokena (podpisanego tokena JWT).

Uwierzytelnianie tokenu (JWT)

Opcja tokena uwierzytelniania może hostować Cloud Anchor przez maksymalnie 365 dni. Ta opcja musi być używana przez kotwicy w chmurze z wartością TTL większą niż 1 dzień. Aby wygenerować tokeny na iOS, musisz mieć na serwerze punkt końcowy, który spełnia te wymagania:

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

  • Punkt końcowy musi za każdym razem generować nowy token. Na przykład:

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

Obecnie jedynym obsługiwanym typem tokena jest podpisany token JWT (token sieciowy JSON podpisany przez konto usługi Google). Wprowadzenie do tokenów JWT znajdziesz na oficjalnej stronie tokena JWT.

Tworzenie konta usługi i klucza podpisywania

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

  1. W menu nawigacyjnym konsoli Google Cloud Platform kliknij Interfejsy API i usługi & gt; Dane logowania.

  2. Wybierz odpowiedni projekt, a następnie 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 do konta usługi kliknij menu Wybierz rolę. Wybierz Konta usługi > Kreator tokenów konta usługi, a następnie kliknij Dalej.

  5. Na stronie Przyznaj użytkownikom dostęp do tego konta usługi kliknij Gotowe. Spowoduje to powrót na stronę Interfejsy API i usługi & gt; Dane logowania.

  6. Przewiń stronę Dane logowania w dół do sekcji Konta usługi i kliknij nazwę właśnie utworzonego konta.

  7. Na stronie Szczegóły konta usługi przewiń w dół do sekcji Klucze i wybierz Dodaj klucz > Utwórz nowy klucz.

  8. Wybierz typ klucza JSON i kliknij Utwórz. Spowoduje to pobranie pliku JSON zawierającego klucz prywatny na Twój komputer. Zapisz pobrany plik klucza JSON w bezpiecznym miejscu.

Tworzenie tokenów na serwerze

Aby utworzyć nowe tokeny (JWT) na serwerze, użyj standardowych bibliotek JWT i pliku JSON, który został bezpiecznie pobrany 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 --jwt --json $KEYFILE $AUDIENCE --cache ""

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

Podpisz token

Aby móc podpisać token JWT, musisz użyć algorytmu RS256 i tych twierdzeń:

  • iss – adres e-mail konta usługi,
  • sub – adres e-mail konta usługi,
  • iat – czas uniksowy wygenerowany przez token w sekundach.
  • exp – iat + 3600 (1 godzina). Czas uniksowy (w sekundach) po wygaśnięciu tokena.
  • aud – odbiorcy. Należy ustawić: https://arcore.googleapis.com.

Niestandardowe deklaracje nie są wymagane w ładunku JWT, ale roszczenie uid może być przydatne do zidentyfikowania odpowiedniego użytkownika.

Jeśli generujesz tokeny JWT w inny sposób, na przykład przy użyciu interfejsu API Google w środowisku zarządzanym przez Google, podpisz tokeny JWT za pomocą deklaracji w tej sekcji. Przede wszystkim upewnij się, że Twoi odbiorcy są prawidłowe.

Przekazywanie tokena do sesji ARCore

Po otrzymaniu tokena przekaż go do sesji ARCore za pomocą XPSession.SetAuthToken():

// Set the token to use when authenticating with the ARCore Cloud Anchor service
// on the iOS platform.
// This should be called each time the application's token is refreshed.
XPSession.SetAuthToken(string authToken);

Gdy przekazujesz token do sesji, pamiętaj o tych kwestiach:

  • Jeśli nie przekażesz prawidłowego tokena, zanim spróbujesz hostować lub rozwiązać kotwicę, wystąpią błędy uwierzytelniania.
  • ARCore ignoruje tokeny zawierające spacje lub znaki specjalne. ARCore ignoruje też wszystkie tokeny, jeśli utworzysz sesję z prawidłowym kluczem interfejsu API. Jeśli zdarzyło Ci się wcześniej używać klucza interfejsu API, którego już nie potrzebujesz, zalecamy usunięcie go w Google Developers Console i usunięcie z aplikacji po przeniesieniu użytkowników do najnowszej wersji.
  • Tokeny tracą zwykle ważność po godzinie. Jeśli istnieje ryzyko, że token wygaśnie, gdy jest używany, uzyskaj nowy token i przekaż go do interfejsu API.

Uwierzytelnianie klucza interfejsu API

Użyj uwierzytelniania klucza interfejsu API, aby hostować i rozwiązywać problemy z kotwicami Cloud z wartością TTL do 24 godzin (1 dzień).

  • W Unity kliknij Edit (Edytuj) > Project Settings (Ustawienia projektu) > ARCore Project Settings (Ustawienia projektu ARCore).
  • Dodaj klucz interfejsu API w polu Klucze interfejsu Cloud Anchor API.

Sprawdź jakość mapowania punktów cech

FeatureMapQuality wskazuje jakość punktów pomiarowych odtworzonych przez ARCore w ciągu ostatnich kilku sekund od danego położenia kamery. Zasadniczo kotwice Cloud hostowane za pomocą funkcji wyższej jakości są zwykle bardziej precyzyjnie rozwiązywane.

Wartość Opis
Insufficient Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund jest niska. Ten stan wskazuje, że ARCore prawdopodobnie będzie mieć trudniejszy dostęp do Cloud Anchor. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana lokalizacja kotwicy Cloud, którą chce hostować, była widoczna pod różnymi kątami.
Sufficient Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund prawdopodobnie wystarczy, aby ARCore rozwiązać problem z Cloud Anchor, chociaż dokładność podawanej pozycji będzie prawdopodobnie mniejsza. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana lokalizacja kotwicy Cloud, którą chce hostować, była widoczna pod różnymi kątami.
Good Jakość punktów cech zidentyfikowanych na podstawie pozycji w ciągu ostatnich kilku sekund prawdopodobnie wystarczy, aby ARCore udało się rozwiązać zadanie Cloud Anchor z dużą dokładnością.

Limity interfejsów API dla żądań hosta i rozstrzygania żądań

Interfejs ARCore API ma następujące limity przepustowości żądań:

Typ limitu Maksimum Czas trwania Dotyczy:
Liczba kotwic bez ograniczeń – projekt
Żądania kotwicy host 30 minuty Adres IP i projekt
Żądania zakotwiczenia kotwicy 300 minuty Adres IP i projekt

Sprawdzone metody zapewniania dobrych wrażeń użytkownikom

Aby zapewnić użytkownikom dobre wrażenia z aplikacją, wykonaj te czynności:

  • Zanim spróbujesz hostować kotwicę, poczekaj kilka sekund po rozpoczęciu sesji. Dzięki temu śledzenie ma czas na stabilizację.
  • Wybierając lokalizację na potrzeby kotwicy, znajdź obszar z funkcjami wizualnymi, które można łatwo odróżnić od siebie. Aby uzyskać jak najlepsze wyniki, unikaj powierzchni odblaskowych i powierzchni, które nie mają cech wizualnych, takich jak puste białe ściany.

  • Trzymaj aparat wytrenowany w środku zainteresowania i poruszaj urządzeniem, aby zmapować otoczenie pod różnymi kątami z zachowaniem zbliżonej odległości fizycznej. Zrób to przez maksymalnie 30 sekund. Dzięki temu będzie można rejestrować więcej danych wizualnych i rozwiązywać problemy.

  • Zadbaj o dobre oświetlenie świata rzeczywistego podczas hostowania i rozwiązywania problemów z zakotwiczeniami w chmurze.

Zasada wycofywania

  • Aplikacje utworzone przy użyciu pakietu SDK ARCore w wersji 1.12.0 lub nowszej podlegają zasadom wycofywania interfejsu Cloud Anchor API.
  • Aplikacje utworzone przy użyciu ARCore SDK w wersji 1.11.0 lub starszej nie mogą hostować ani rozwiązywać problemów z kotwiskami Cloud w wyniku korzystania ze starszej wersji interfejsu API ARCore.

Co dalej?