Geospatial API für Android-Apps aktivieren (Kotlin/Java)

Konfigurieren Sie die Einstellungen Ihrer App so, dass die Geospatial API verwendet werden kann.

Voraussetzungen

Machen Sie sich mit den grundlegenden AR-Konzepten und zur Konfiguration einer ARCore-Sitzung vertraut, bevor Sie fortfahren.

Beispiel-App und Codelab

In diesem Video erfahren Sie, wie Sie mithilfe der Geospatial API eine Anwendung erstellen, die raumbezogene Daten anzeigt und Inhalte an realen Orten platziert.

Dieselben Schritte finden Sie auch in der Dokumentation zu raumbezogenem Codelab. Informationen zum Ausführen der im Video erstellten Beispielanwendung finden Sie im Schnellstart zu ARCore Geospatial.

Weitere Informationen zur Geospatial API finden Sie in der Einführung in die Geospatial API.

Wenn du zum ersten Mal mit ARCore entwickelst, findest du unter Erste Schritte Informationen zu Software- und Hardwareanforderungen und Voraussetzungen sowie weitere Informationen zu den von dir verwendeten Plattformen.

Achte darauf, dass deine Entwicklungsumgebung die ARCore SDK-Anforderungen erfüllt, wie in der Kurzanleitung beschrieben.

ARCore API aktivieren

Bevor Sie das Visual Positioning System (VPS) in Ihrer App verwenden können, müssen Sie zuerst die ARCore API in einem neuen oder vorhandenen Google Cloud-Projekt aktivieren. Dieser Dienst ist für das Hosting, die Speicherung und die Auflösung von raumbezogenen Ankern verantwortlich.

Die schlüssellose Autorisierung wird bevorzugt, aber auch die Autorisierung über API-Schlüssel wird unterstützt.

Der App die erforderlichen Bibliotheken hinzufügen

Nachdem Sie Ihre App zum Aufrufen der ARCore API autorisiert haben, müssen Sie Bibliotheken hinzufügen, um raumbezogene Funktionen in Ihrer App zu aktivieren.

Richte in der Datei build.gradle deiner App die Google Play-Dienste so ein, dass sie die Standortbibliothek der Play-Dienste enthalten.

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)'
}

Raumbezogene Funktionen in der Sitzungskonfiguration aktivieren

Ändern Sie vor dem Erstellen der Sitzung den GeospatialMode in der Sitzungskonfiguration in ENABLED:

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

Solange der Geospatial-Modus auf ENABLED gesetzt ist, darf die Anwendung geografische Informationen vom Visual Positioning System (VPS) abrufen.

Nutzer auffordern, die Nutzung von Gerätedaten zuzulassen

Apps, die die ARCore Geospatial API verwenden, müssen dem Nutzer eine Aufforderung anzeigen, um die Verwendung der Daten auf seinem Gerät zu bestätigen und zuzulassen. Weitere Informationen finden Sie unter Anforderungen an den Datenschutz für Nutzer.

Gerätekompatibilität prüfen

Wie in der quickstart beschrieben, unterstützen nicht alle Geräte, die ARCore unterstützen, auch die Geospatial API.

Rufen Sie Session.checkGeospatialModeSupported() auf, um das Gerät des Nutzers auf Kompatibilität zu prüfen. Wenn dabei „false“ zurückgegeben wird, versuchen Sie nicht, die Sitzung zu konfigurieren (siehe unten), da sonst ein UnsupportedConfigurationException ausgelöst wird.

Nutzer während der Laufzeit um die Berechtigung zur Standortermittlung bitten

Ihre App muss zur Laufzeit Berechtigungen zur Standortermittlung anfordern.

Damit du die ARCore Geospatial API verwenden kannst, muss deine App die folgenden zusätzlichen Berechtigungen registrieren:

  • ACCESS_FINE_LOCATION, um den Standort des Nutzers genau zu bestimmen.

  • ACCESS_COARSE_LOCATION für die ungenaue Standortbestimmung des Nutzers und die Einhaltung der Datenschutzanforderungen für Nutzer. Die Geospatial API kann jedoch nicht für den ungefähren Standort konfiguriert werden und API-Anfragen schlagen fehl, wenn der Nutzer diese Berechtigung festgelegt hat. Weitere Informationen hierzu finden Sie unten.

  • ACCESS_INTERNET, um den ARCore Geospatial API-Dienst zu kontaktieren

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

Auf Geräten mit Android 12 oder höher können Nutzer anfordern, dass Ihre App nur auf Informationen zum ungefähren Standort zugreifen darf. Damit diese Anfrage verarbeitet werden kann, müssen für Ihre App die Berechtigung ACCESS_COARSE_LOCATION und ACCESS_FINE_LOCATION konfiguriert sein, wie oben gezeigt. Du musst beide Berechtigungen zur Standortermittlung konfigurieren.

Wenn Nutzer jedoch eine ungefähre Position angeben, kann die Geospatial API nicht den genauen Standort abrufen, den sie benötigt. Der raumbezogene Dienst lässt sich nicht selbst konfigurieren, wenn Ihre App nur den ungefähren Standort angibt. Deine App kann die Geospatial API nicht mit dem ungefähren Standort verwenden.

Raumbezogene Verfügbarkeit am aktuellen Standort des Geräts prüfen

Da die Geospatial API eine Kombination aus VPS und GPS verwendet, um eine raumbezogene Position zu bestimmen, kann die API verwendet werden, solange das Gerät seinen Standort bestimmen kann. In Gebieten mit geringer GPS-Genauigkeit, wie z. B. in Innenräumen und dicht bebauten städtischen Umgebungen, setzt die API auf eine VPS-Abdeckung, um Positionen mit hoher Genauigkeit zu erzeugen. Unter typischen Bedingungen ist mit VPS eine Positionsgenauigkeit von etwa 5 Metern und eine Rotationsgenauigkeit von 5 Grad zu erwarten. Mit Session.checkVpsAvailabilityAsync() können Sie feststellen, ob an einem bestimmten Standort eine VPS-Abdeckung vorliegt.

Die Geospatial API kann auch in Regionen verwendet werden, in denen keine VPS-Abdeckung vorliegt. In Außenbereichen mit wenigen oder gar keinen Hindernissen über dem Kopf reicht das GPS unter Umständen aus, um eine Position mit hoher Genauigkeit zu erstellen.

Nächste Schritte