Dowiedz się, jak korzystać z kotwic Cloud we własnych aplikacjach.
Wymagania wstępne
Zanim przejdziesz dalej, zapoznaj się z podstawowymi pojęciami dotyczącymi AR i dowiedz się, jak skonfigurować sesję ARCore.
Jeśli dopiero zaczynasz korzystać z Kotwic Cloud, dowiedz się, jak działają kotwice i kotwice w chmurze.
Włącz interfejs ARCore API
Zanim zaczniesz używać Cloud Anchor w swojej aplikacji, musisz włączyć ARCore API w nowym lub istniejącym projekcie Google Cloud Platform. Ta usługa jest odpowiedzialna za przechowywanie, przechowywanie i rozwiązywanie problemów z kotwicami Cloud.
Autoryzowanie aplikacji do wywoływania interfejsu ARCore API
Musisz zezwolić aplikacji na wywoływanie interfejsu ARCore API w celu hostowania i rozwiązywania kotwic Cloud. Aplikacje hostujące i rozwiązujące Cloud Anchor z czasem TTL przekraczającym 1 dzień muszą używać autoryzacji bez klucza.
Autoryzacja bez kluczy
Używaj autoryzacji bez klucza do hostowania i rozwiązywania problemów z kotwicami Cloud z TTL między 1 a 365 dni.
Domyślna strategia autoryzacji w przypadku nowych projektów Unity utworzonych w ARCore SDK 1.24.0 lub nowszym to DoNotUse. Ma to na celu uniemożliwienie tworzenia aplikacji, które zawierają niepotrzebne biblioteki. Jeśli Twoja aplikacja korzysta z Cloud Anchor i została utworzona za pomocą pakietu ARCore SDK w wersji 1.24.0 lub nowszej, musisz ręcznie włączyć autoryzację w Ustawieniach projektu > Zarządzanie wtyczkami XR > Rozszerzenia ARCore.
Kliknij Edytuj > Ustawienia projektu > XR Plug-in Management > ARCore Rozszerzenia, a następnie w menu Strategia uwierzytelniania Androida wybierz opcję Bez klucza.
Spowoduje to usunięcie wszystkich kluczy interfejsu API zapisanych w poprzednim ustawieniu Cloud Anchors i dodanie niezbędnych zależności oraz wyjątków ProGuard. Jeśli zdarzyło Ci się już korzystać z klucza interfejsu API, którego już nie potrzebujesz, zalecamy usunięcie go w Google Cloud Platform Console i usunięcie go z aplikacji po przeniesieniu użytkowników do najnowszej wersji.
Wygeneruj klucz podpisywania SHA-1.
W menu Edit wybierz Project Settings > Player > Publishing Settings.
Kliknij Keystore Manager i utwórz nowy klucz.
Skopiuj klucz podpisywania SHA-1 (wklej go w następnym kroku).
Utwórz identyfikator klienta OAuth swojej aplikacji na Androida w konsoli Google Cloud przy użyciu identyfikatora aplikacji i odcisku cyfrowego podpisu SHA-1. Spowoduje to powiązanie aplikacji na Androida z projektem Google Cloud Platform.
Autoryzacja klucza interfejsu API
Użyj autoryzacji klucza interfejsu API do hostowania i rozwiązywania problemów z kotwicami Cloud z TTL do 24 godzin (1 dzień).
Domyślna strategia autoryzacji w przypadku nowych projektów Unity utworzonych w ARCore SDK 1.24.0 lub nowszym to DoNotUse. Ma to na celu uniemożliwienie tworzenia aplikacji, które zawierają niepotrzebne biblioteki. Jeśli Twoja aplikacja korzysta z Cloud Anchor i została utworzona za pomocą pakietu ARCore SDK w wersji 1.24.0 lub nowszej, musisz ręcznie włączyć autoryzację w Ustawieniach projektu > Zarządzanie wtyczkami XR > Rozszerzenia ARCore.
Kliknij Edytuj > Ustawienia projektu > XR Plug-in Management > ARCore Extensions, a następnie w menu Android Authentication Strategy wybierz opcję API Key (Klucz interfejsu API).
Uzyskaj klucz interfejsu API tego projektu z konsoli Google Cloud.
Kliknij Edytuj > Ustawienia projektu > XR Plug-in Management > ARCore Extensions i dodaj klucz interfejsu API w polu Cloud Anchor API Keys.
Włączanie w aplikacji funkcji Cloud Anchor
Po autoryzacji aplikacji do wywoływania ARCore API musisz włączyć w niej funkcje Cloud Anchors.
- Kliknij Edytuj > Ustawienia projektu > XR Plug-In Management > ARCore Extensions.
- W sekcji Funkcje opcjonalne wybierz Cloud zakotwiczone.
Włącz możliwości Cloud Anchor w konfiguracji sesji
Po włączeniu funkcji Cloud zakotwiczonych w aplikacji włącz jej funkcje konfiguracji sesji AR, aby mogła ona komunikować się z interfejsem ARCore API:
- Upewnij się, że folder Assets projektu zawiera obiekt skryptu ARCoreExtensionsConfig. Aby je utworzyć, kliknij prawym przyciskiem myszy w panelu Zasoby i wybierz Utwórz > XR > Konfiguracja rozszerzeń ARCore.
W folderze Assets wybierz zasób ARCoreExtensionsConfig i ustaw włączony tryb Cloud Anchor.
Skonfiguruj obiekt gry ARCore Extensions, aby użyć konfiguracji ARCoreExtensionsConfig. W panelu Hierarchia znajdź obiekt gry ARCore Extensions, który został utworzony podczas wstępnej konfiguracji rozszerzeń ARCore, i połącz pole ARCore Extensions Config z obiektem ARCoreExtensionsConfig w folderze Assets.
Hostowanie zakotwiczenia w chmurze
Hosting rozpoczyna się od połączenia z ARAnchorManager.HostCloudAnchorAsync(). ARCore prześle dane wizualne, pozycje urządzenia i pozycję kotwicy do interfejsu ARCore API. Interfejs API przetwarza te informacje, aby utworzyć mapę cech 3D. W rezultacie zwraca unikalny identyfikator kotwicy Cloud na urządzeniu.
Możesz też przedłużyć okres ważności hostowanej kotwicy za pomocą interfejsu ARCore Cloud Anchor Management API.
Aby dokończyć hostowanie Cloud Anchor, wykonaj te czynności:
- Zadzwoń pod numer
ARAnchorManager.HostCloudAnchorAsync(). - Rozpocznij koordynację, aby poczekać, aż obietnica się powiedzie. Więcej informacji znajdziesz w artykule Koordynacje w Unity.
- Sprawdź stan wyniku, aby ustalić, czy operacja się udała, lub zinterpretuj kod błędu, jeśli się nie udało.
- Udostępnij wynik Cloud zakotwiczenia innym klientom i użyj go, aby rozwiązać problem z kotwicą Cloud w
ARAnchorManagerExtensions.ResolveCloudAnchorAsync().
Sprawdź jakość mapowania punktów cech
ARCoreExtensions.FeatureMapQuality wskazuje jakość punktów prezentowanych przez ARCore w ciągu ostatnich kilku sekund od danej pozycji kamery. Rozwiązujemy problem z kotwicami w chmurze obsługiwanymi przez funkcje wyższej jakości. Użyj metody ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting(), aby oszacować jakość mapy funkcji w przypadku danej pozycji.
| 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ć problemy z rozpoznawaniem kotwicy Cloud. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana pozycja kotwicy w chmurze była widoczna z różnych kątów. |
Sufficient |
Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund prawdopodobnie wystarczy do rozwiązania ARCore w celu rozwiązania Cloud Anchor, chociaż dokładność podawanej pozycji będzie prawdopodobnie mniejsza. Zachęć użytkownika do przeniesienia urządzenia, tak aby pożądana pozycja kotwicy w chmurze była widoczna z różnych kątów. |
Good |
Jakość punktów cech określonych na podstawie pozycji w ciągu ostatnich kilku sekund jest prawdopodobnie wystarczająca, aby ARCore udało się rozwiązać zadanie Cloud Anchor z dużą dokładnością. |
Rozwiązywanie problemów z hostowaną wcześniej kotwicą
Wywołaj ARAnchorManagerExtensions.ResolveCloudAnchorAsync(), aby rozwiązać problem z hostowaną chmurą. Interfejs ARCore API okresowo porównuje elementy wizualne ze sceny z mapą funkcji 3D kotwicy, aby określić położenie i orientację użytkownika względem kotwicy. Po znalezieniu dopasowania interfejs API zwraca pozycję hostowanej wiadomości Cloud Anchor.
Możesz zainicjować decyzje dotyczące kilku kotwic Cloud w kolejności. Jednocześnie może być powiązanych maksymalnie 40 działań Cloud Anchor.
Anulowanie operacji lub usuwanie kotwicy Cloud
Komponent ARCloudAnchor.OnDestroy() jest wywoływany automatycznie, gdy komponent ARCloudAnchor zostanie usunięty z obiektu gry, który go zawiera. Spowoduje to odłączenie i zwolnienie bazowego obiektu Cloud Anchor.
Sprawdzanie stanu wyniku operacji Cloud Anchor
Użyj CloudAnchorState, aby sprawdzić stan wyniku operacji hostingu lub rozwiązywania problemów, w tym błędy.
| Wartość | Opis |
|---|---|
ErrorResolvingCloudIdNotFound |
Nie udało się rozwiązać problemu, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora kotwicy Cloud. |
ErrorHostingDatasetProcessingFailed |
Hostowanie nie powiodło się, ponieważ serwer nie mógł przetworzyć zbioru danych dla danej kotwicy. Spróbuj ponownie, gdy urządzenie zbierze więcej danych ze środowiska. |
ErrorHostingServiceUnavailable |
Interfejs ARCore API był nieosiągalny. Możliwych jest kilka przyczyn takiej sytuacji. Urządzenie może być w trybie samolotowym lub nie ma połączenia z internetem. Minął limit czasu wysłania żądania do serwera. Nieprawidłowe połączenie sieciowe, niedostępność DNS, problemy z zaporą sieciową lub inne problemy, które mogą mieć wpływ na możliwość połączenia urządzenia z interfejsem ARCore API. |
ErrorInternal |
Hostowanie lub rozwiązywanie zadania dla tej kotwicy zakończyło się błędem wewnętrznym. Aplikacja nie powinna próbować odzyskać dostępu do tego błędu. |
ErrorNotAuthorized |
Aplikacja nie może połączyć się z interfejsem ARCore API z powodu nieprawidłowej autoryzacji. Poprawną strategię autoryzacji znajdziesz w sekcji Ustawienia projektu > XR > Rozszerzenia ARCore. |
ErrorResolvingPackageTooNew |
Nie udało się rozwiązać problemu z Cloud Anchor, ponieważ pakiet rozszerzeń ARCore do rozwiązania tej kotwicy jest nowszy niż wersja, w której jest hostowana, i niezgodna z tą wersją. |
ErrorResolvingPackageTooOld |
Nie udało się znaleźć rozwiązania Cloud Anchor, ponieważ pakiet rozszerzeń ARCore do rozwiązania Cloud zakotwiczenia jest starszy lub niezgodny z wersją używaną do hostowania go. |
ErrorResourceExhausted |
Aplikacja wyczerpała limit żądań przypisany do danego projektu Google Cloud. W Google Developers Console musisz poprosić o dodatkowy limit ARCore API dla Twojego projektu. |
Success |
Hostowanie lub rozwiązanie zadania dla tej kotwicy zostało zakończone. |
Limity interfejsów API dla żądań hosta i rozwiązywania
Interfejs ARCore API ma następujące limity przepustowości żądań:
| Typ limitu | Maksimum | Czas trwania | Dotyczy: |
|---|---|---|---|
| Liczba kotwic | bez ograniczeń | Nie dotyczy | projekt |
| Żądania zakotwiczenia kotwicy | 30 | minuty | Adres IP i projekt |
| Żądania zakotwiczenia rozstrzygnięcia | 300 | minuty | Adres IP i projekt |
Sprawdzone metody zapewniania wygody użytkownikom
Aby zapewnić użytkownikom pozytywne wrażenia z aplikacji, wykonaj te czynności:
- Po rozpoczęciu sesji poczekaj kilka sekund, zanim spróbujesz umieścić kotwicę (przez umieszczenie obiektu itp.). Dzięki temu śledzenie ma czas na stabilizację.
- Wybierając lokalizację na potrzeby kotwicy, znajdź obszar z cechami wizualnymi, które można łatwo odróżnić od siebie. Aby uzyskać 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 przesuwaj urządzenie wokół niego, aby obrazować otoczenie pod różnymi kątami, zachowując przy tym mniej więcej taką samą odległość fizyczną. Pomoże to w przechwytywaniu większej ilości danych wizualnych i zwiększa dokładność.
Zadbaj o wystarczające oświetlenie w rzeczywistym środowisku podczas hostowania i rozwiązywania problemów z Cloud Anchor.
Zasady wycofywania
- Aplikacje utworzone przy użyciu ARCore SDK w wersji 1.12.0 lub nowszej są objęte zasadami 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 Cloud zakotwiczonych, ponieważ pakiet SDK korzysta ze starszego, wycofanego interfejsu ARCore API.
Co dalej?
- Więcej informacji na temat używania ARCore w aplikacji znajdziesz w dokumentacji referencyjnej ARCore Extensions for AR Foundation.