Konfigurowanie interfejsu Geospatial API w aplikacji

Odpowiednie urządzenia z XR

Te wskazówki pomogą Ci tworzyć treści na te typy urządzeń z XR.

Więcej informacji o typach urządzeń XR →

Więcej informacji o typach urządzeń XR →

Aby używać interfejsu Geospatial API w aplikacji, musisz skonfigurować aplikację tak, aby miała dostęp do interfejsu ARCore API w Google Cloud. Ten interfejs API zawiera Visual Positioning Service, który zapewnia dokładne pozycjonowanie na podstawie danych z Google Street View.

Z tego przewodnika dowiesz się, jak skonfigurować projekt w chmurze Google Cloud z włączonym odpowiednim interfejsem API i metodami autoryzacji, aby uzyskać dostęp do interfejsu API.

Skonfiguruj projekt Google Cloud lub użyj istniejącego projektu

Jeśli masz już projekt Google Cloud, wybierz go.

Otwórz selektor projektów

Jeśli nie masz projektu, utwórz go.

Tworzenie nowego projektu

Włączanie interfejsu ARCore API

Aby korzystać z interfejsu ARCore API, musisz go włączyć w projekcie.

Włączanie interfejsu ARCore API

Konfigurowanie autoryzacji w Google Cloud

Aplikacja na Androida może komunikować się z interfejsem ARCore API za pomocą 2 różnych metod autoryzacji: autoryzacji bez klucza (OAuth 2.0), która jest zalecaną metodą, oraz autoryzacji za pomocą klucza interfejsu API:

• Autoryzacja bez klucza wykorzystuje kombinację nazwy pakietu aplikacji i odcisku cyfrowego klucza podpisywania do autoryzacji aplikacji.

• Klucz interfejsu API to ciąg znaków, który identyfikuje projekt w chmurze Google. Klucze interfejsu API nie są zwykle uważane za bezpieczne, ponieważ są zazwyczaj dostępne dla klientów. Do komunikacji z interfejsem ARCore API rozważ użycie autoryzacji bez klucza.

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

Poproś o wymagane uprawnienia

Aby korzystać z interfejsu Geospatial API w ARCore z Jetpack XR, aplikacja musi poprosić o te uprawnienia w czasie działania:

• ACCESS_FINE_LOCATION: wymagane do określenia dokładnej lokalizacji użytkownika.

Na urządzeniach mobilnych interfejs Geospatial API wymaga też tych uprawnień:

• android.permission.CAMERA: wymagane do uzyskania dostępu do aparatu urządzenia.
• android.permission.INTERNET: wymagane do komunikacji z usługami Google Cloud.

Dostęp do sesji

Dostęp do informacji geoprzestrzennych przez środowisko wykonawcze Jetpack XR Session, które musi zostać utworzone przez aplikację.

Konfigurowanie sesji

Interfejs Geospatial API nie jest domyślnie włączony w sesjach XR. Aplikacja musi wyraźnie włączyć tę funkcję, konfigurując GeospatialMode w Session. Dostępne są te tryby:

• GeospatialMode.SPATIAL: interfejs Geospatial API jest włączony. Interfejs Geospatial API używa systemu pozycjonowania wizualnego (VPS), danych z systemu pozycjonowania globalnego (GPS) i czujników ruchu urządzenia, aby określić położenie geoprzestrzenne urządzenia. Ten tryb nie jest dostępny na inteligentnych okularach.
• GeospatialMode.INERTIAL: interfejs Geospatial API jest włączony w trybie oszczędzania baterii. Do określania położenia geoprzestrzennego urządzenia interfejs Geospatial API używa tylko GPS-u i czujników ruchu urządzenia. Ten tryb jest dostępny tylko na inteligentnych okularach.
• GeospatialMode.DISABLED: interfejs Geospatial API jest wyłączony. Podczas przechodzenia z innego trybu do tego trybu interfejs Geospatial API zwalnia wszystkie pozyskane zasoby i przestaje śledzić.

Nie wszystkie urządzenia obsługują wszystkie tryby geoprzestrzenne. Więcej informacji znajdziesz w artykule GeospatialMode. Użyj XrDevice.isGeospatialSupported, aby sprawdzić, czy dany GeospatialMode jest obsługiwany.

Poniższy przykładowy kod pokazuje, jak ustawić GeospatialMode za pomocą Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

Wyświetlanie użytkownikowi prośby o zezwolenie na korzystanie z danych urządzenia

Aplikacje, które używają interfejsu Geospatial API z ARCore for Jetpack XR, muszą wyświetlać użytkownikowi prośbę o potwierdzenie i zezwolenie na korzystanie z danych z jego urządzenia. Więcej informacji znajdziesz w wymaganiach dotyczących ochrony prywatności użytkowników.

Używanie obiektu geoprzestrzennego

Po skonfigurowaniu sesji pobierz obiekt Geospatial za pomocą metody Geospatial.getInstance. Używaj obiektu Geospatial tylko wtedy, gdy jego stan to GeospatialTrackingState.RUNNING.

Poniższe przykłady kodu pokazują, jak monitorować stan danych geoprzestrzennych za pomocą Geospatial.state.

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

Wartości dokładności

Gdy interfejs Geospatial API jest włączony, podaje 3 wartości dokładności: dokładność poziomą, pionową i orientacji. Te wartości dokładności są aktualizowane z czasem i mogą być bardziej precyzyjne, gdy zostanie zebranych więcej danych. Większe wartości oznaczają mniejszą dokładność i są definiowane jako promień przedziału ufności 68%. Innymi słowy, istnieje 68-procentowe prawdopodobieństwo, że prawdziwa wartość mieści się w podanym promieniu wartości szacunkowej.

Użyj Geospatial.State.horizontalAccuracy, verticalAccuracy i orientationYawAccuracy, aby uzyskać bieżące wartości dokładności.

Do prawidłowego działania aplikacja może wymagać określonego poziomu precyzji. Na przykład aplikacja może poczekać, aż dokładność pozioma będzie mniejsza niż 5 metrów, zanim wyrenderuje treści wirtualne. Aby zwiększyć prawdopodobieństwo uzyskania danych o wyższej dokładności, aplikacja powinna instruować użytkowników, aby rozejrzeli się po okolicy, najlepiej po budynkach lub innych obiektach o wysokim poziomie szczegółowości wizualnej, które są widoczne w Google Street View. Użyj Geospatial.checkVpsAvailability, aby określić, czy VPS jest dostępny w danej lokalizacji.

Co dalej?

Gdy interfejs Geospatial API jest prawidłowo skonfigurowany w aplikacji, może ona wykonywać te czynności:

• Konwertowanie pozycji lokalnych na urządzeniu na pozycje geoprzestrzenne
• Renderowanie treści w pozycjach geoprzestrzennych