Geospatial API für die NDK-App für Android aktivieren (C)

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.

Wenn Sie eine Beispiel-App ausführen möchten, die die hier beschriebene Funktionalität demonstriert, lesen Sie den ARCore Geospatial Schnellstart für Android für Java. Die Beispielanwendung im Schnellstart ist in Java geschrieben. Die Codebeispiele in diesem Dokument beziehen sich auf die gleiche Funktionalität, die in C geschrieben ist.

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 für Java 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:

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

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

Nicht alle Geräte, die ARCore unterstützen, unterstützen auch die Geospatial API, wie in der quickstart für Java beschrieben.

Rufen Sie ArSession_isGeospatialModeSupported() 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 ArStatus sonst ein AR_ERROR_UNSUPPORTED_CONFIGURATION meldet.

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