Geospatial API in Ihrer App einrichten

XR‑Geräte, für die der Leitfaden gilt

Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.

Informationen zu XR-Gerätetypen →

Informationen zu XR-Gerätetypen →

Wenn Sie die Geospatial API in Ihrer App verwenden möchten, muss Ihre App so eingerichtet sein, dass sie auf die ARCore API in Google Cloud zugreifen kann. Diese API enthält den Visual Positioning Service, der mithilfe von Daten aus Google Street View eine genaue Positionsbestimmung ermöglicht.

In diesem Leitfaden erfahren Sie, wie Sie ein Google Cloud-Projekt einrichten, in dem die richtige API und die richtigen Autorisierungsmethoden für den Zugriff auf die API aktiviert sind.

Google Cloud-Projekt einrichten oder vorhandenes Projekt verwenden

Wenn Sie bereits ein Google Cloud-Projekt haben, wählen Sie es aus.

Zur Projektauswahl

Wenn Sie noch kein Projekt haben, erstellen Sie eines.

Neues Projekt erstellen

ARCore API aktivieren

Wenn Sie die ARCore API verwenden möchten, müssen Sie sie in Ihrem Projekt aktivieren.

ARCore API aktivieren

Autorisierung für Google Cloud einrichten

Eine Android-App kann über zwei verschiedene Autorisierungsmethoden mit der ARCore API kommunizieren: die schlüssellose Autorisierung (OAuth 2.0), die empfohlene Methode, und die API-Schlüssel-Autorisierung:

• Bei der schlüssellosen Autorisierung wird eine Kombination aus dem Paketnamen der Anwendung und dem Fingerabdruck des Signaturschlüssels verwendet, um Ihre Anwendung zu autorisieren.

• Ein API-Schlüssel ist ein String, der ein Google Cloud-Projekt identifiziert. API-Schlüssel gelten im Allgemeinen nicht als sicher, da sie in der Regel für Clients zugänglich sind. Sie können die schlüssellose Autorisierung verwenden, um mit der ARCore API zu kommunizieren.

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

Erforderliche Berechtigungen anfordern

Wenn Sie die Geospatial API in ARCore mit Jetpack XR verwenden möchten, muss Ihre App die folgenden Laufzeitberechtigungen anfordern:

• ACCESS_FINE_LOCATION: Erforderlich, um den genauen Standort eines Nutzers zu bestimmen.

Auf Mobilgeräten sind für die Geospatial API außerdem die folgenden Berechtigungen erforderlich:

• android.permission.CAMERA: Erforderlich, um auf die Kamera des Geräts zuzugreifen.
• android.permission.INTERNET: Erforderlich für die Kommunikation mit Google Cloud-Diensten.

Auf eine Sitzung zugreifen

Sie können über eine Jetpack XR-Laufzeit Session, die von Ihrer App erstellt werden muss, auf Geospatial-Informationen zugreifen.

Sitzung konfigurieren

Die Geospatial API ist in XR-Sitzungen nicht standardmäßig aktiviert. Ihre Anwendung muss sie explizit aktivieren, indem Sie einen GeospatialMode für den Session konfigurieren. Folgende Modi sind verfügbar:

• GeospatialMode.SPATIAL: Die Geospatial API ist aktiviert. Die Geospatial API verwendet Daten des Visual Positioning System (VPS), des Global Positioning System (GPS) und die Bewegungssensoren des Geräts, um die raumbezogene Position des Geräts zu bestimmen. Dieser Modus ist auf Smart Glasses-Geräten nicht verfügbar.
• GeospatialMode.INERTIAL: Die Geospatial API ist im Energiesparmodus aktiviert. Die Geospatial API verwendet nur GPS und die Bewegungssensoren des Geräts, um die geografische Position des Geräts zu bestimmen. Dieser Modus ist nur auf Intelligent Eyewear-Geräten verfügbar.
• GeospatialMode.DISABLED: Die Geospatial API ist deaktiviert. Beim Wechsel von einem anderen Modus in diesen Modus gibt die Geospatial API alle erworbenen Ressourcen frei und beendet das Tracking.

Nicht alle Geräte unterstützen alle Geospatial-Modi. Weitere Informationen finden Sie unter GeospatialMode. Verwenden Sie XrDevice.isGeospatialSupported, um zu prüfen, ob ein bestimmter GeospatialMode unterstützt wird.

Im folgenden Codebeispiel wird gezeigt, wie Sie mit Session.configure ein GeospatialMode festlegen.

// 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

Nutzer auffordern, die Verwendung von Gerätedaten zuzulassen

Apps, die die Geospatial API mit ARCore für Jetpack XR verwenden, müssen den Nutzer auffordern, die Verwendung von Daten von seinem Gerät zu bestätigen und zu erlauben. Weitere Informationen finden Sie in den Datenschutzanforderungen für Nutzer.

Geospatial-Objekt verwenden

Nachdem die Sitzung konfiguriert wurde, rufen Sie das Geospatial-Objekt mit Geospatial.getInstance ab. Verwenden Sie das Objekt Geospatial nur, wenn der Status GeospatialTrackingState.RUNNING ist.

Die folgenden Codebeispiele zeigen, wie Sie den Geospatial-Status mit Geospatial.state überwachen.

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

Genauigkeitswerte verstehen

Wenn die Geospatial API aktiviert ist, liefert sie drei Genauigkeitswerte: horizontale, vertikale und Ausrichtungsgenauigkeit. Diese Genauigkeitswerte werden im Laufe der Zeit aktualisiert und können mit zunehmender Datenmenge präziser werden. Größere Werte weisen auf eine geringere Genauigkeit hin und werden als Radius eines Konfidenzniveaus von 68 % definiert. Mit anderen Worten: Es besteht eine Wahrscheinlichkeit von 68 %, dass der tatsächliche Wert innerhalb des angegebenen Radius des geschätzten Werts liegt.

Verwenden Sie Geospatial.State.horizontalAccuracy, verticalAccuracy und orientationYawAccuracy, um die aktuellen Genauigkeitswerte abzurufen.

Ihre App benötigt möglicherweise ein bestimmtes Maß an Genauigkeit, um richtig zu funktionieren. Beispielsweise kann es sinnvoll sein, mit dem Rendern virtueller Inhalte zu warten, bis die horizontale Genauigkeit weniger als 5 Meter beträgt. Um die Wahrscheinlichkeit zu erhöhen, dass Daten mit höherer Genauigkeit abgerufen werden, sollte Ihre App Nutzer auffordern, sich in ihrer Umgebung umzusehen, vorzugsweise auf Gebäude oder andere Merkmale mit vielen visuellen Details, die in Google Street View vorhanden sind. Mit Geospatial.checkVpsAvailability können Sie feststellen, ob das VPS am angegebenen Standort verfügbar ist.

Nächste Schritte

Wenn die Geospatial API in Ihrer App richtig eingerichtet ist, kann Ihre App Folgendes tun:

• Zwischen gerätelokalen und Geospatial-Positionen konvertieren
• Inhalte an Geopositionen rendern