Dowiedz się, jak używać kotwic w chmurze we własnych aplikacjach.
Wymagania wstępne
Zanim przejdziesz dalej, upewnij się, że znasz podstawowe pojęcia związane z AR i wiesz, jak skonfigurować sesję ARCore.
Jeśli dopiero zaczynasz korzystać z usług zakotwiczonych w chmurze:
- Upewnij się, że wiesz, jak działają kotwice i kotwice w chmurze.
- Przeczytaj quickstart do usługi kotwicy Cloud, w której znajdziesz wymagania systemowe, instrukcje konfiguracji i instalacji.
Włącz interfejs ARCore API
Zanim użyjesz w swojej aplikacji kotwicy Cloud, musisz włączyć ARCore API w nowym lub istniejącym projekcie Google Cloud Platform. Ta usługa odpowiada za hostowanie, przechowywanie i rozwiązywanie problemów z kotwicami w chmurze.
Autoryzowanie aplikacji do wywoływania interfejsu ARCore API
Musisz autoryzować aplikację do wywoływania interfejsu ARCore API w celu hostowania i rozpatrywania kotwic w chmurze. Aplikacje hostujące i rozwiązujące kotwice w chmurze o czasie TTL dłuższym niż 1
dzień muszą korzystać z autoryzacji bez klucza.
Autoryzacja bez klucza
Użyj autoryzacji bez klucza, aby hostować i zakotwiczyć kotwice Cloud z wartością TTL wynoszącą od 1
do 365
dni.
- Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
W konsoli Google Cloud utwórz identyfikator klienta OAuth dla swojej aplikacji na Androida, używając identyfikatora aplikacji oraz odcisku cyfrowego SHA-1 certyfikatu podpisywania. Spowoduje to powiązanie aplikacji na Androida z projektem Google Cloud Platform.
Aby pobrać odcisk cyfrowy certyfikatu podpisywania debugowania:
- Otwórz panel narzędzi Gradle w projekcie Android Studio.
- Kliknij <nazwa-projektu> > Lista zadań > android.
- Uruchom zadanie signingReport.
- Skopiuj odcisk cyfrowy SHA-1 dla wersji debugowania do pola Odcisk cyfrowy certyfikatu SHA-1 w konsoli Google Cloud.
- Otwórz panel narzędzi Gradle w projekcie Android Studio.
Dodaj
com.google.android.gms:play-services-auth:16+
do zależności aplikacji.Jeśli używasz ProGuard, dodaj go do pliku
build.gradle
aplikacji przy użyciubuildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }
Dodaj do pliku
proguard-rules.pro
aplikacji:-keep class com.google.android.gms.common.** { *; } -keep class com.google.android.gms.auth.** { *; } -keep class com.google.android.gms.tasks.** { *; }
Autoryzacja klucza interfejsu API
Użyj autoryzacji klucza interfejsu API, aby hostować i rozstrzygać kotwice Cloud z wartością TTL do 24 godzin (1
dzień).
- Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
- Uzyskaj klucz interfejsu API dla tego projektu z konsoli Google Cloud.
W Android Studio dodaj do projektu nowy klucz interfejsu API. Umieść klucz interfejsu API w elemencie
<meta-data>
w elemencie<application>
w elemencieapp/manifests/AndroidManifest.xml
Twojej aplikacji:<meta-data android:name="com.google.android.ar.API_KEY" android:value="API_KEY"/>
Włącz możliwości usługi Cloud Anchor w konfiguracji sesji
Gdy włączysz funkcję kotwicy Cloud w aplikacji, włącz jej funkcje w konfiguracji sesji AR w aplikacji, aby mogły komunikować się z interfejsem ARCore API:
Java
Config config = new Config(session); config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED); session.configure(config);
Kotlin
val config = Config(session) config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED session.configure(config)
Hostowanie kotwicy w chmurze
Hosting rozpoczyna się od wywołania metody hostCloudAnchorAsync()
. ARCore prześle do interfejsu ARCore API dane wizualne, pozycje urządzeń i pozycję kotwicy. Interfejs API przetwarza te informacje, aby utworzyć mapę funkcji 3D, a ostatecznie zwraca do urządzenia unikalny identyfikator kotwicy w chmurze.
Możesz też przedłużyć czas życia hostowanej kotwicy za pomocą interfejsu ARCore Cloud Anchor Management API.
Aby zakończyć hosting usługi kotwicy w chmurze, aplikacja powinna wykonać te czynności:
- Zadzwoń pod numer
hostCloudAnchorAsync()
. - Poczekaj na wywołanie zwrotne lub stale sprawdzaj stan przyszły, dopóki się nie zakończy.
- Sprawdź stan wyniku, aby określić, czy operacja się powiodła, lub zinterpretuj kod błędu, jeśli się nie uda.
- Udostępnij wynik identyfikatora kotwicy Cloud innym klientom i użyj go do rozpoznania kotwicy Cloud za pomocą:
resolveCloudAnchorAsync()
.
Sprawdzanie jakości mapowania punktów cech
Session.FeatureMapQuality
wskazuje jakość punktów cech zarejestrowanych przez ARCore w ciągu ostatnich kilku sekund w danej pozycji kamery. Kotwice w chmurze hostowane z użyciem funkcji wyższej jakości są zwykle dokładniej rozpoznawane. Użyj narzędzia Session.estimateFeatureMapQualityForHosting()
, aby oszacować jakość mapy obiektów w danej pozycji kamery.
Wartość | Opis |
---|---|
INSUFFICIENT |
Jakość punktów cech zidentyfikowanych na podstawie pozycji w ostatnich kilku sekundach jest niska. Ten stan wskazuje, że ARCore prawdopodobnie będzie mieć większe problemy z rozpoznaniem usługi kotwicy w chmurze. Zachęć użytkownika do przesunięcia urządzenia tak, aby żądana pozycja kotwicy w chmurze, którą chce hostować, była widoczna 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 zakotwiczenia w chmurze przez ARCore, ale dokładność zatwierdzonej pozycji prawdopodobnie się zmniejszy. Zachęć użytkownika do przesunięcia urządzenia tak, aby żądana pozycja kotwicy w chmurze, którą chce hostować, była widoczna pod różnymi kątami. |
GOOD |
Jakość punktów cech zidentyfikowanych w pozycji w ciągu ostatnich kilku sekund wystarczy, aby aplikacja ARCore mogła skutecznie rozpoznać kotwicę w chmurze z dużą dokładnością. |
Rozwiązywanie wcześniej hostowanej kotwicy
Wywołaj resolveCloudAnchorAsync()
, aby znaleźć hostowaną kotwicę Cloud. Interfejs ARCore API okresowo porównuje cechy 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 kotwicy Cloud.
Możesz zainicjować rozstrzygnięcia dla wielu zakotwiczonych w chmurze w sekwencji. W danym momencie może istnieć do 40 równoczesnych operacji w Cloud Anchor.
Anulowanie operacji lub usuwanie kotwicy w chmurze
Wywołaj cancel()
, aby anulować oczekującą operację kotwicy Cloud.
Wywołaj detach()
, aby usunąć z aplikacji zakotwiczoną chmurę, która została już rozwinięta.
Sprawdzanie stanu wyniku operacji zakotwiczonej w chmurze
Użyj parametru Anchor.CloudAnchorState, aby sprawdzić stan wyniku operacji hostingu lub rozwiązywania problemów, w tym błędy.
Wartość | Opis |
---|---|
ERROR_CLOUD_ID_NOT_FOUND |
Nie udało się rozwiązać problemu, ponieważ interfejs ARCore API nie mógł znaleźć podanego identyfikatora kotwicy w chmurze. |
ERROR_HOSTING_DATASET_PROCESSING_FAILED |
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. |
ERROR_HOSTING_SERVICE_UNAVAILABLE |
Interfejs ARCore API był nieosiągalny. Możliwych jest kilka przyczyn takiej sytuacji. Urządzenie może być w trybie samolotowym lub nie ma działającego połączenia z internetem. Żądanie wysłane do serwera mogło zostać przekroczony i nie uzyskać odpowiedzi. Może to być złe połączenie sieciowe, niedostępność DNS, problemy z zaporą sieciową lub coś innego, co wpływa na zdolność urządzenia do łączenia się z interfejsem ARCore API. |
ERROR_INTERNAL |
Zadanie hostingu lub rozwiązywania problemów z tą kotwicą zostało zakończone z błędem wewnętrznym. Aplikacja nie powinna podejmować prób usunięcia konta po tym błędzie. |
ERROR_NOT_AUTHORIZED |
Autoryzacja podana przez aplikację jest nieprawidłowa.
|
ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
Nie udało się ustalić wersji pakietu SDK Cloud, ponieważ wersja pakietu SDK użyta do rozpoznania kotwicy jest nowsza i niezgodna z wersją użytą do jej hostowania. |
ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
Nie udało się ustalić wersji pakietu SDK Cloud, ponieważ wersja pakietu SDK użyta do rozpoznania kotwicy jest starsza i niezgodna z wersją użytą do jej hostowania. |
ERROR_RESOURCE_EXHAUSTED |
Aplikacja wyczerpała limit żądań przypisany do danego projektu Google Cloud. Aby zgłosić prośbę o zwiększenie limitu interfejsu ARCore API w projekcie, skorzystaj z Google Developers Console. |
SUCCESS |
Udało się wykonać zadanie hostingu lub rozwiązywania problemów tej kotwicy. |
Limity interfejsów API dotyczące żądań hostów i rozwiązywania
W interfejsie ARCore API obowiązują następujące limity przepustowości żądań:
Typ limitu | Maksimum | Czas trwania | Dotyczy: |
---|---|---|---|
Liczba kotwic | bez ograniczeń | Nie dotyczy | projektu |
Żądania kotwicy hosta | 30 | minuta | Adres IP i projekt |
resolve żądań zakotwiczonych | 300 | minuta | Adres IP i projekt |
Sprawdzone metody dbania o wygodę użytkowników
Poproś ich o wykonanie tych czynności, aby zapewnić im dobre wrażenia z aplikacji:
- Zaczekaj kilka sekund po rozpoczęciu sesji, zanim spróbujesz hostować kotwicę (np. umieszczając obiekt). To zapewni trochę czasu na ustabilizowanie się śledzenia.
- Wybierając miejsce, w którym ma się wyświetlać kotwica, znajdź obszar z elementami wizualnymi, które łatwo się od siebie odróżnić. Aby uzyskać najlepsze wyniki, unikaj powierzchni odbijających światło i powierzchni pozbawionych elementów wizualnych, np. pustych białych ścian.
Kamera powinna być ustawiona w taki sposób, aby znalazła się w centrum zainteresowania, i poruszać urządzenie po całym centrum, aby zmapować środowisko z różnych kątów, zachowując mniej więcej taką samą odległość jak tutaj. Pomoże to rejestrować więcej danych wizualnych i zwiększyć dokładność rozpoznawania.
Podczas hostowania i rozmowywania kotwic w chmurze upewnij się, że w rzeczywistym środowisku jest wystarczająco oświetlone.
Zasady wycofywania
- Aplikacje utworzone przy użyciu pakietu SDK ARCore w wersji 1.12.0 lub nowszej są objęte zasadami wycofywania interfejsu Cloud Anchor API.
- Aplikacje utworzone przy użyciu pakietu SDK w wersji 1.11.0 lub starszej ARCore nie mogą hostować ani wyświetlać kotwic w chmurze, ponieważ pakiet SDK używa starszego, wycofanego interfejsu ARCore API.
Co dalej?
- Skorzystaj z ćwiczenia z programowania ARCore Cloud Anchors z trwałymi kotwicami Cloud, aby utworzyć aplikację.
- Zapoznaj się z krótkim wprowadzeniem do korzystania z usług zakotwiczonych w chmurze, aby poznać 2 przykładowe aplikacje dotyczące hostowania i rozwiązywania problemów z kotwicami w chmurze.
- Zarządzaj kotwicami w chmurze poza aplikacją ARCore za pomocą interfejsu Cloud Anchors Management API.
- Więcej informacji o korzystaniu z ARCore w aplikacji znajdziesz w dokumentacji referencyjnej Androida.