Włączanie interfejsu Geospatial API dla aplikacji NDK na Androida (C)

Skonfiguruj ustawienia aplikacji, aby mogła korzystać z interfejsu Geospatial API.

Wymagania wstępne

Zanim przejdziesz dalej, upewnij się, że rozumiesz podstawowe zagadnienia związane z rozszerzoną rzeczywistością oraz że wiesz, jak skonfigurować sesję ARCore.

Jeśli chcesz uruchomić przykładową aplikację, która demonstruje opisane tutaj funkcje, skorzystaj z artykułu ARCore Geospatial API – samouczek dla Androida (w języku Java). Przykładowa aplikacja w Krótkim wprowadzeniu jest napisana w języku Java. Przykłady kodu w tym dokumencie dotyczą tej samej funkcji napisanej w języku C.

Więcej informacji o Geospatial API znajdziesz w artykule Wprowadzenie do Geospatial API.

Jeśli dopiero zaczynasz tworzyć aplikacje z wykorzystaniem ARCore, zapoznaj się z artykułem Pierwsze kroki, aby dowiedzieć się więcej o wymaganiach sprzętowych i programowych, wymaganiach wstępnych oraz innych informacjach dotyczących platform, których używasz.

Upewnij się, że Twoje środowisko programistyczne spełnia wymagania pakietu ARCore SDK opisane w artykule Szybki start dotyczącym Javy.

Włącz interfejs ARCore API

Zanim użyjesz w aplikacji systemu pozycjonowania wizualnego (VPS), musisz najpierw włączyć interfejs ARCore API w nowym lub istniejącym projekcie Google Cloud. Ta usługa odpowiada za hostowanie, przechowywanie i rozwiązywanie kotwic geoprzestrzennych.

Preferowana jest autoryzacja bezkluczowa, ale obsługiwana jest też autoryzacja za pomocą klucza API.

Dodawanie wymaganych bibliotek do aplikacji

Po autoryzowaniu aplikacji do wywoływania interfejsu ARCore API musisz dodać biblioteki, aby włączyć w niej funkcje geoprzestrzenne.

W pliku build.gradle aplikacji skonfiguruj Usługi Google Play, aby uwzględnić bibliotekę Usług Google Play Location.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

Włączanie funkcji geoprzestrzennych w konfiguracji sesji

Zanim utworzysz sesję, zmień wartość parametru GeospatialMode w konfiguracji sesji na ENABLED:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

Gdy tryb geoprzestrzenny jest ustawiony na ENABLED, aplikacja może uzyskiwać informacje geograficzne z systemu VPS (Visual Positioning System).

Prośba o zezwolenie na użycie danych urządzenia

Aplikacje korzystające z interfejsu ARCore Geospatial API muszą wyświetlać użytkownikowi prośbę o potwierdzenie i zezwolenie na używanie danych z urządzenia. Więcej informacji znajdziesz w wymaganiach dotyczących prywatności użytkowników.

Sprawdzanie zgodności z urządzeniami

Nie wszystkie urządzenia, które obsługują ARCore, obsługują też interfejs Geospatial API, jak opisano w przewodniku szybkiego startu dla Javy.

Aby sprawdzić, czy urządzenie użytkownika jest zgodne, zadzwoń pod numer ArSession_isGeospatialModeSupported(). Jeśli zwróci wartość false, nie próbuj konfigurować sesji (poniżej), ponieważ ArStatus wyśle raport AR_ERROR_UNSUPPORTED_CONFIGURATION.

Prośba o dostęp do lokalizacji w czasie działania aplikacji

Aplikacja musi poprosić o dostęp do lokalizacji w czasie działania.

Aby korzystać z interfejsu ARCore Geospatial API, aplikacja musi zarejestrować te dodatkowe uprawnienia:

  • ACCESS_FINE_LOCATION dokładne określenie lokalizacji użytkownika.

  • ACCESS_COARSE_LOCATION w celu niedokładnego określania lokalizacji użytkownika i spełniania wymagań dotyczących prywatności użytkowników. Interfejsu Geospatial API nie można jednak skonfigurować tak, aby działał z przybliżoną lokalizacją, a żądania interfejsu API będą się kończyć niepowodzeniem, gdy użytkownik ustawi to uprawnienie. Więcej informacji znajdziesz poniżej.

  • ACCESS_INTERNET aby skontaktować się z usługą ARCore Geospatial API.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Na urządzeniach z Androidem w wersji 12 lub nowszej użytkownicy mogą poprosić o dostęp do aplikacji tylko do przybliżonej lokalizacji. Aby spełnić to żądanie, aplikacja musi mieć skonfigurowane uprawnienie ACCESS_COARSE_LOCATION oraz ACCESS_FINE_LOCATION, jak pokazano powyżej. Musisz skonfigurować oba uprawnienia dostępu do lokalizacji.

Jednak gdy użytkownicy podają przybliżoną lokalizację, uniemożliwia to interfejsowi Geospatial API uzyskanie wymaganej dokładnej lokalizacji. Usługa geoprzestrzenna nie pozwoli na skonfigurowanie, jeśli Twoja aplikacja podaje tylko przybliżoną lokalizację. Aplikacja nie może używać interfejsu Geospatial API z nieprecyzyjną lokalizacją.

Sprawdzanie dostępności danych geoprzestrzennych w bieżącej lokalizacji urządzenia

Ponieważ interfejs Geospatial API do określania pozycji geoprzestrzennej wykorzystuje kombinację VPS i GPS, można go używać, dopóki urządzenie jest w stanie określić swoją lokalizację. W obszarach o niskiej dokładności GPS, takich jak wnętrza budynków i gęsto zaludnione obszary miejskie, interfejs API będzie korzystać z usługi VPS, aby generować pozy o wysokiej dokładności. W typowych warunkach usługa VPS zapewnia dokładność pozycjonowania na poziomie około 5 metrów oraz dokładność obrotu na poziomie 5 stopni. Aby sprawdzić, czy dana lokalizacja ma usługę VPS, użyj ArSession_checkVpsAvailabilityAsync().

Interfejsu Geospatial API można też używać na obszarach, na których nie ma pokrycia VPS. W otoczeniu zewnętrznym z niewielką liczbą przeszkód nad głową lub bez nich GPS może wystarczyć do wygenerowania pozy z wysoką dokładnością.

Co dalej?