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

Skonfiguruj ustawienia aplikacji, aby umożliwić korzystanie z interfejsu Geospatial API.

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 chcesz uruchomić przykładową aplikację, która prezentuje opisane tu funkcje, przeczytaj krótkie wprowadzenie do ARCore Geospatial Geospatial na Androida dla języka Java. Przykładowa aplikacja w krótkim wprowadzeniu jest napisana w Javie. Przykładowe fragmenty kodu w tym dokumencie dotyczą tych samych funkcji, które zostały opisane w języku C.

Więcej informacji o interfejsie Geospatial API znajdziesz we wprowadzeniu do interfejsu Geospatial API.

Jeśli nie masz doświadczenia w programowaniu z ARCore, przeczytaj Pierwsze kroki, aby uzyskać informacje o wymaganiach dotyczących oprogramowania i sprzętu, wymagań wstępnych oraz innych informacji specyficznych dla używanych przez Ciebie platform.

Upewnij się, że Twoje środowisko programistyczne spełnia wymagania ARCore SDK, zgodnie z opisem w krótkim wprowadzeniu do języka Java.

Włącz interfejs ARCore API

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

Preferowana jest autoryzacja bez klucza, ale obsługiwana jest również autoryzacja klucza interfejsu API.

Dodaj wymagane biblioteki do aplikacji

Po autoryzacji 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, by uwzględnić bibliotekę lokalizacji Usług Google Play.

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łącz funkcje geoprzestrzenne w konfiguracji sesji

Zanim utworzysz sesję, zmień 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 wartość ENABLED, aplikacja może uzyskiwać informacje geograficzne z systemu Visual Positioning System (VPS).

Proś użytkownika o zgodę na użycie danych z urządzenia

Aplikacje korzystające z interfejsu ARCore Geospatial API muszą wyświetlać użytkownikowi prośbę o potwierdzenie i zezwolenie na korzystanie z danych z jego urządzenia. Więcej informacji znajdziesz w artykule Wymagania dotyczące prywatności użytkownika.

Sprawdź zgodność urządzenia

Nie wszystkie urządzenia, które obsługują ARCore, również obsługują interfejs Geospatial API, jak opisano we quickstart dotyczącym języka Java.

Aby sprawdzić zgodność urządzenia użytkownika, wywołaj metodę ArSession_isGeospatialModeSupported(). Jeśli ta opcja zwróci wartość false (fałsz), nie próbuj skonfigurować sesji (poniżej). Jeśli to zrobisz, ArStatus zgłosi AR_ERROR_UNSUPPORTED_CONFIGURATION.

Pytaj użytkownika o dostęp do lokalizacji podczas działania

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

Aby można było używać interfejsu ARCore Geospatial API, aplikacja musi zarejestrować te dodatkowe uprawnienia:

  • ACCESS_FINE_LOCATION, aby dokładnie określić lokalizację użytkownika.

  • ACCESS_COARSE_LOCATION – za nieprecyzyjne określanie lokalizacji użytkownika i zapewnienie zgodności z wymaganiami dotyczącymi prywatności. Interfejsu Geospatial API nie można jednak skonfigurować do pracy z przybliżoną lokalizacją. Gdy użytkownik nada to uprawnienie, żądania do interfejsu API będą kończyć się niepowodzeniem. 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ć, aby aplikacja miała dostęp tylko do informacji o przybliżonej lokalizacji. Aby aplikacja mogła obsłużyć to żądanie, musi mieć skonfigurowane uprawnienie ACCESS_COARSE_LOCATION oraz ACCESS_FINE_LOCATION, jak pokazano powyżej. Musisz skonfigurować oba uprawnienia dostępu do lokalizacji.

Jeśli jednak użytkownicy określą przybliżoną lokalizację, interfejs Geospatial API nie będzie mógł uzyskać dokładnej lokalizacji. Nie można skonfigurować usługi geoprzestrzennej, jeśli aplikacja podaje tylko przybliżoną lokalizację. Twoja aplikacja nie może używać interfejsu Geospatial API z przybliżoną lokalizacją.

Sprawdź dostępność danych geoprzestrzennych w bieżącej lokalizacji urządzenia

Interfejs Geospatial API używa kombinacji VPS i GPS do określania pozycji geoprzestrzennej, dlatego interfejsu API można używać, jeśli urządzenie może określić jego lokalizację. Na obszarach o niskiej dokładności sygnału GPS, takich jak przestrzenie wewnątrz budynków czy gęsty obszar miejski, interfejs API będzie wykorzystywać dane VPS do generowania ujęć o wysokiej dokładności. W typowych warunkach architektura VPS zapewnia dokładność pozycjonowania wynoszącą około 5 metrów i dokładność obrotu co 5 stopni. Użyj narzędzia ArSession_checkVpsAvailabilityAsync(), aby określić, czy dana lokalizacja ma zasięg VPS.

Interfejsu Geospatial API można też używać na obszarach, które nie są objęte zasięgiem VPS. W warunkach na zewnątrz, w których występuje niewiele przeszkód z powietrza lub nie ma ich wcale, do wykonania pozycji z dużą dokładnością GPS może wystarczyć sygnał GPS.

Co dalej