Przewodnik dla programistów Cloud Anchors dla Unity (AR Foundation)

Dowiedz się, jak używać usług zakotwiczonych Cloud we własnych aplikacjach.

Wymagania wstępne

Upewnij się, że znasz podstawowe pojęcia związane z AR. i dowiedz się, jak skonfigurować sesję ARCore, zanim przejdziesz dalej.

Jeśli dopiero zaczynasz korzystać z Cloud Anchors, upewnij się, że wiesz, jak działają kotwice i Cloud Anchor.

Włączanie interfejsu ARCore API

Zanim zaczniesz używać Cloud Anchors w swojej aplikacji, musisz włączyć w niej interfejs ARCore API.

Włącz funkcje Cloud Anchor w konfiguracji sesji

Po włączeniu funkcji Cloud Anchors w swojej aplikacji włącz je w konfiguracji sesji AR aplikacji, aby umożliwić komunikację z interfejsem ARCore API:

Hostowanie kotwicy Cloud

Hosting zaczyna się od wywołania ARAnchorManager.HostCloudAnchorAsync(). ARCore prześle do interfejsu ARCore API dane wizualne, pozycje urządzeń i pozycję kotwicy. Następnie interfejs API przetwarza te informacje, aby utworzyć mapę funkcji 3D, co ostatecznie zwraca na urządzeniu unikalny identyfikator Cloud Anchor dla kotwicy.

Czas życia hostowanej kotwicy możesz też przedłużyć za pomocą interfejsu ARCore Cloud Anchor Management API.

Aby dokończyć hosting Cloud Anchor, Twoja aplikacja powinna wykonać te czynności:

  1. Zadzwoń pod numer ARAnchorManager.HostCloudAnchorAsync().
  2. Uruchom współprogram, aby zaczekać na uzyskanie wyniku przez obietnicę. Więcej informacji znajdziesz w sekcji Korutyny w Unity.
  3. Sprawdzanie stanu wyniku , aby określić, czy operacja się powiodła, lub zinterpretować kod błędu, jeśli operacja się nie udała.
  4. Udostępnij wynikowy identyfikator Cloud Anchor innym klientom i użyj go do rozpoznania elementu Cloud Anchor z: ARAnchorManagerExtensions.ResolveCloudAnchorAsync()

Sprawdź jakość mapowania punktów obiektu

ARCoreExtensions.FeatureMapQuality wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund przy danej pozycji kamery. Elementy zakotwiczone w chmurze hostowane przy użyciu funkcji o wyższej jakości są zwykle dokładniej rozpoznawane. Użyj narzędzia ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting(), aby uzyskać oszacowanie jakości mapy cech w przypadku danej pozycji aparatu.

Wartość Opis
Insufficient Jakość punktów cech zidentyfikowanych na podstawie pozycji w ciągu ostatnich kilku sekund jest niska. Ten stan oznacza, że usługa ARCore prawdopodobnie będzie miała większe trudności z rozwiązywaniem Cloud Anchor. Poproś użytkownika o przesunięcie urządzenia tak, aby punkt zakotwiczenia w chmurze, który chce hostować, był widoczny pod różnymi kątami.
Sufficient Jakość punktów cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca do rozpoznania przez ARCore rozwiązania Cloud Anchor, choć dokładność ustalenia pozycji będzie prawdopodobnie mniejsza. Poproś użytkownika o przesunięcie urządzenia tak, aby punkt zakotwiczenia w chmurze, który chce hostować, był widoczny pod różnymi kątami.
Good Jakość punktów cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca, aby ARCore mogła z dużą dokładnością rozpoznać punkt zakotwiczenia w chmurze.

Rozwiązywanie problemów z hostowaną wcześniej kotwicą

Wywołaj ARAnchorManagerExtensions.ResolveCloudAnchorAsync(), aby rozpoznać hostowaną usługę Cloud Anchor. Interfejs ARCore API okresowo porównuje elementy wizualne sceny z mapą funkcji 3D reklamy zakotwiczonej, aby określić położenie i orientację użytkownika względem reklamy zakotwiczonej. Po znalezieniu dopasowania interfejs API zwraca pozycję hostowanej usługi Cloud Anchor.

Możesz inicjować sekwencje dla wielu elementów Cloud Anchor. Jednocześnie może istnieć maksymalnie 40 operacji Cloud Anchor.

Anulowanie operacji i usuwanie usługi Cloud Anchor

Pole ARCloudAnchor.OnDestroy() jest wywoływane automatycznie, gdy komponent ARCloudAnchor zostanie usunięty z obiektu gry, który go zawiera. Spowoduje to odłączenie i zwolnienie bazowego natywnego obiektu Cloud Anchor.

Sprawdzanie stanu wyniku operacji Cloud Anchor

Użyj CloudAnchorState do sprawdzania stanu wyników operacji hostingu lub rozwiązywania, w tym błędów.

Wartość Opis
ErrorResolvingCloudIdNotFound Nie udało się rozwiązać problemu, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora Cloud Anchor.
ErrorHostingDatasetProcessingFailed Nie udało się przeprowadzić hostingu, ponieważ serwer nie może przetworzyć zbioru danych w przypadku danej kotwicy. Spróbuj ponownie, gdy urządzenie zbierze więcej danych o środowisku.
ErrorHostingServiceUnavailable Interfejs ARCore API był nieosiągalny. Możliwych jest kilka przyczyn takiej sytuacji. Urządzenie może być w trybie samolotowym lub nie mieć działającego połączenia z internetem. Możliwe, że upłynął limit czasu żądania wysłanego do serwera i nie otrzymano odpowiedzi. Przyczyną może być nieprawidłowe połączenie sieciowe, niedostępność DNS, problem z zaporą sieciową lub inny problem, który może mieć wpływ na zdolność urządzenia do nawiązania połączenia z interfejsem ARCore API.
ErrorInternal Zadanie hostingu lub rozwiązywania tej kotwicy zakończyło się błędem wewnętrznym. Aplikacja nie powinna próbować naprawić tego błędu.
ErrorNotAuthorized Aplikacja nie może komunikować się z interfejsem ARCore API z powodu nieprawidłowej autoryzacji. Zaznacz Ustawienia projektu > XR > ARCore Extensions, aby uzyskać prawidłową strategię autoryzacji.
ErrorResolvingPackageTooNew Nie udało się rozwiązać problemu Cloud Anchor, ponieważ pakiet rozszerzeń ARCore użyty do rozwiązania Cloud Anchor jest nowszy i niezgodny z wersją używaną do hostowania tego elementu.
ErrorResolvingPackageTooOld Nie udało się rozwiązać problemu Cloud Anchor, ponieważ pakiet rozszerzeń ARCore użyty do rozwiązania Cloud Anchor jest starszy i niezgodny z wersją używaną do hostowania usługi.
ErrorResourceExhausted Aplikacja wyczerpała limit żądań przypisany do danego projektu Google Cloud. W Google Developers Console musisz poprosić o zwiększenie limitu dla interfejsu ARCore API w projekcie.
Success Zadanie hostingu lub rozwiązywania tej kotwicy zostało ukończone.

Limity interfejsu API dotyczące hostów i realizacji żądań

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

Typ limitu Maksimum Czas trwania Dotyczy:
Liczba reklam zakotwiczonych bez ograniczeń Nie dotyczy projekt
Żądania hosta kotwicy 30 minuta Adres IP i projekt
Rozwiązywanie żądań zakotwiczenia 300 minuta Adres IP i projekt

Sprawdzone metody dbania o wygodę użytkowników

Poleć im, aby wykonali te czynności, by zapewnić wygodę korzystania z aplikacji:

  • Zanim spróbujesz umieścić reklamę zakotwiczoną, odczekaj kilka sekund po rozpoczęciu sesji (umieszczając obiekt itp.). Dzięki temu śledzenie ustabilizuje się po pewnym czasie.
  • Wybierając lokalizację, w której ma się wyświetlać reklama zakotwiczona, staraj się znaleźć obszar z elementami wizualnymi, które łatwo odróżnić od innych. Aby uzyskać jak najlepszy wynik, unikaj powierzchni odbijających światło oraz bez elementów wizualnych, takich jak puste białe ściany.

  • Trzymaj kamerę tak, aby znalazł się w centrum zainteresowania, i poruszaj urządzeniem wokół siebie w centrum zainteresowania, aby nanieść na mapę środowisko pod różnymi kątami, zachowując przy tym podobną odległość fizyczną. Pomoże to rejestrować więcej danych wizualnych i ułatwi rozwiązywanie problemów.

  • Podczas hostowania i rozwiązywania problemów zakotwiczonych Cloud Anchor upewnij się, że w rzeczywistym środowisku jest wystarczające oświetlenie.

Zasady wycofywania

  • Aplikacje z pakietem ARCore SDK 1.12.0 lub nowszym podlegają zasadom wycofywania interfejsu Cloud Anchor API.
  • Aplikacje utworzone za pomocą pakietu SDK ARCore lub starszego nie mogą hostować ani realizować elementów Cloud Anchor, ponieważ pakiet SDK używa starszego, wycofanego interfejsu ARCore API.

Co dalej?