Przewodnik dla programistów Cloud Anchors dla Androida (Kotlin/Java)

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.

  1. Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.

  2. 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.

  3. Dodaj com.google.android.gms:play-services-auth:16+ do zależności aplikacji.

  4. Jeśli używasz ProGuard, dodaj go do pliku build.gradle aplikacji przy użyciu

    buildTypes {
  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ń).

  1. Włącz ARCore API w nowym lub istniejącym projekcie Google Cloud Platform.
  2. Uzyskaj klucz interfejsu API dla tego projektu z konsoli Google Cloud.

  3. W Android Studio dodaj do projektu nowy klucz interfejsu API. Umieść klucz interfejsu API w elemencie <meta-data> w elemencie <application> w elemencie app/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:

  1. Zadzwoń pod numer hostCloudAnchorAsync().
  2. Poczekaj na wywołanie zwrotne lub stale sprawdzaj stan przyszły, dopóki się nie zakończy.
  3. Sprawdź stan wyniku, aby określić, czy operacja się powiodła, lub zinterpretuj kod błędu, jeśli się nie uda.
  4. 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.
  • Być może w projekcie Google Cloud nie włączono interfejsu ARCore API lub operacja, którą próbujesz wykonać, jest niedozwolona.
  • Jeśli stosujesz uwierzytelnianie za pomocą klucza interfejsu API: klucz interfejsu API w pliku manifestu jest nieprawidłowy, nieautoryzowany lub jego brak. Może też zakończyć się niepowodzeniem, jeśli klucz interfejsu API jest ograniczony do zbioru aplikacji niezawierających bieżącej aplikacji.
  • Jeśli korzystasz z autoryzacji bez klucza: nie udało Ci się utworzyć klienta OAuth.
  • Usługi Google Play nie są zainstalowane, są zbyt stare lub działają nieprawidłowo (np. usługi przestały działać z powodu obciążenia pamięci).
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?