ARCore aktivieren

Auf dieser Seite wird beschrieben, wie du ARCore-Funktionen in deinen Android NDK-Projekten aktivierst. Gehen Sie dazu so vor:

  1. AR-erforderliche oder AR-optionale Erweiterungen zum Manifest hinzufügen
  2. Build-Abhängigkeiten hinzufügen
  3. Führen Sie Laufzeitprüfungen aus, um dafür zu sorgen, dass das Gerät ARCore-unterstützt ist und die Google Play-Dienste für AR darauf installiert sind.
  4. Achte darauf, dass deine App den Core Datenschutzanforderungen entspricht

Google Play-Dienste für AR

ARCore SDKs bietet AR-Funktionen für ARCore-fähige Geräte, auf denen Google Play Services for AR (ARCore) installiert ist.

Google Play-Dienste für AR wird auf den meisten unterstützten Geräten automatisch installiert und aktualisiert.

Um eine AR-Sitzung starten zu können, müssen Apps

  1. Prüfen Sie, ob ARCore unterstützt wird. Rufen Sie dazu ArCoreApk_checkAvailability auf.
  2. Rufe ArCoreApk_requestInstall auf, um zu prüfen, ob Google Play-Dienste für AR installiert und auf dem neuesten Stand ist und die erforderlichen Daten für ARCore-Geräteprofile heruntergeladen wurden.

AR-Erforderlich oder AR optional zum Manifest hinzufügen

Eine App, die AR-Funktionen unterstützt, kann auf zwei Arten konfiguriert werden: AR erforderlich und AR optional.

AR erforderlich

Damit diese App verwendet werden kann, ist eine AR-erforderlichApp erforderlichARCore-unterstütztes Gerät mit Google Play-Diensten für ARvorinstalliert.

Weitere Informationen finden Sie unter AR-Apps im Google Play Store veröffentlichen.

Wenn Sie Ihre App als AR erforderlich deklarieren möchten, ändern Sie Ihren AndroidManifest.xml so, dass er die folgenden Einträge enthält:

<uses-permission android:name="android.permission.CAMERA"/>

<!-- Limits app visibility in the Google Play Store to ARCore supported devices
     (https://developers.google.com/ar/devices). -->
<uses-feature android:name="android.hardware.camera.ar" android:required="true"/>

<application …>
    …

  <!-- "AR Required" app, requires "Google Play Services for AR" (ARCore)
       to be installed, as the app does not include any non-AR features. -->
  <meta-data android:name="com.google.ar.core" android:value="required" />

</application>

Ändern Sie dann das build.gradle Ihrer App so, dass ein minSdkVersion von mindestens 24 angegeben wird:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR (optional)

Eine AR-optionale App hat optionale AR-Funktionen, die nur auf ARCore-fähigen Geräten aktiviert sind, auf denen Google Play-Dienste für AR installiert ist.

  • Optionale Apps auf AR können auf Geräten installiert und ausgeführt werden, die ARCore nicht unterstützen.

  • Wenn Nutzer eine optionale AR-App installieren, installiert der Google Play Store nicht automatisch Google Play-Dienste für AR mit der App.

Wenn Sie Ihre App als AR-optional deklarieren möchten, ändern Sie Ihren AndroidManifest.xml so, dass er die folgenden Einträge enthält:

<uses-permission android:name="android.permission.CAMERA" />

<!-- If your app was previously AR Required, don't forget to remove the
 `<uses-feature android:name="android.hardware.camera.ar" />` entry, as
 this would limit app visibility in the Google Play Store to only
 ARCore supported devices. -->

<application …>
    …

    <!-- "AR Optional" app, contains non-AR features that can be used when
         "Google Play Services for AR" (ARCore) is not available. -->
    <meta-data android:name="com.google.ar.core" android:value="optional" />
</application>

Ändern Sie dann das build.gradle Ihrer App so, dass ein minSdkVersion von mindestens 14 angegeben wird:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

Build-Abhängigkeiten hinzufügen

So fügen Sie die ARCore-Bibliothek zu Ihrem Android Studio-Projekt hinzu:

  1. Achte darauf, dass die build.gradle-Datei deines Projekts das Maven-Repository von Google enthält.

    allprojects {
    repositories {
        google()
            ...
    
  2. Extrahiert native Bibliotheken aus ARCore aar.

    Die nativen Bibliotheken sind in der ARCore-ARA-Datei enthalten. Wenn sie in einem C/C++-Projekt verwendet werden sollen, müssen sie aus dem Archiv extrahiert und direkt darauf verwiesen werden. Füge dazu einer build.gradle-Datei eine benutzerdefinierte Aufgabe hinzu (z. B. app/build.gradle).

    Die Headerdatei für ARCore arcore_c_api.h ist im GitHub SDK-Projekt enthalten:

    Definieren Sie eine Variable für ein Verzeichnis im app/build-Verzeichnis. Die nativen Bibliotheken werden in dieses Verzeichnis extrahiert. Erstelle auch eine Gradle-Konfiguration, um die Extraktionsaufgaben und Daten zu speichern.

    /*
    The ARCore aar library contains the native shared libraries. These are
    extracted before building to a temporary directory.
    */
    def arcore_libpath = "${buildDir}/arcore-native"
    
    // Create a configuration to mark which aars to extract .so files from
    configurations { natives }
    
    

    Erstellen Sie eine Aufgabe zum Kopieren der nativen Bibliotheken aus der aar-Datei und fügen Sie sie den Build-Abhängigkeiten hinzu

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done so that NDK builds can access these libraries.
      task extractNativeLibraries() {
         // Extract every time.
         outputs.upToDateWhen { false }
    
         doFirst {
              configurations.natives.files.each { f ->
                  copy {
                      from zipTree(f)
                      into arcore_libpath
                      include "jni/**/*"
                  }
              }
          }
      }
    
      tasks.whenTaskAdded {
          task-> if (task.name.contains("external") && !task.name.contains("Clean")) {
              task.dependsOn(extractNativeLibraries)
          }
      }
    
  3. Konfigurieren Sie die nativen Build-Flags, um die Standorte an die externen Build-Tools zu übergeben.

    Dieses Beispiel stammt aus den Beispielen im GitHub-Projekt.

          externalNativeBuild {
              cmake {
                  cppFlags "-std=c++11", "-Wall"
                  arguments "-DANDROID_STL=c++_static",
                          "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                          "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
              }
          }
    

  4. Fügen Sie die Abhängigkeiten sowohl für die Java- als auch für die native Bibliotheken hinzu.

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.32.0'
          natives 'com.google.ar:core:1.32.0'
          ...
     }
    
  5. Auf native Bibliotheken in CMakeLists.txt verweisen

    # Import the ARCore library.
    add_library(arcore SHARED IMPORTED)
    set_target_properties(arcore PROPERTIES IMPORTED_LOCATION
                  ${ARCORE_LIBPATH}/${ANDROID_ABI}/libarcore_sdk_c.so
                  INTERFACE_INCLUDE_DIRECTORIES ${ARCORE_INCLUDE}
    )
    

Laufzeitprüfungen durchführen

ARCore installieren

Alle AR-Apps müssen ArCoreApk_requestInstall() aufrufen, bevor eine ARCore-Sitzung erstellt werden kann. ArCoreApk_requestInstall() prüft, ob eine kompatible Version der Google Play-Dienste für AR installiert ist (möglicherweise veraltet oder wurde vom Nutzer manuell entfernt) und fordert den Nutzer auf, den Dienst zu installieren, wenn er nicht vorhanden ist.

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    // Ensure Google Play Services for AR and ARCore device profile data are
    // installed and up to date.
    ArStatus error = ArCoreApk_requestInstall(
        env, activity, user_requested_install, &install_status);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    switch (install_status) {
      case AR_INSTALL_STATUS_INSTALLED:
        break;
      case AR_INSTALL_STATUS_INSTALL_REQUESTED:
        // When this method returns `AR_INSTALL_STATUS_INSTALL_REQUESTED`:
        // 1. This activity will be paused.
        // 2. The user is prompted to install or update Google Play
        //    Services for AR (market://details?id=com.google.ar.core).
        // 3. ARCore downloads the latest device profile data.
        // 4. This activity is resumed. The next invocation of
        //    ArCoreApk_requestInstall will either return
        //    `AR_INSTALL_STATUS_INSTALLED` or throw an exception if the
        //    installation or update did not succeed.
        install_requested_ = true;
        return;
    }

    // Request camera permissions.

    error = ArSession_create(env, context, &ar_session_);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    // Configure session
  }

  // Normal onResume behavior
}

Wenn ArCoreApk_requestInstall() den Wert AR_INSTALL_STATUS_INSTALL_REQUESTED zurückgibt, wird die aktuelle Aktivität pausiert und der Nutzer wird aufgefordert, den Dienst zu installieren oder zu aktualisieren. Die onResume() der Aktivität wird noch einmal ausgeführt, wenn der Nutzer zur Aktivität zurückkehrt.

Prüfen, ob ARCore unterstützt wird (nur AR optional)

Optionale Apps für AR können mit ArCoreApk_checkAvailability() feststellen, ob das aktuelle Gerät ARCore unterstützt. Auf einem Gerät, das ARCore nicht unterstützt, sollten Apps AR-bezogene Funktionen deaktivieren und die zugehörigen UI-Elemente ausblenden.

void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

Wenn Nutzer eine AR-Funktion verwenden möchten, sollte in der App Google Play-Dienste für AR installiert sein. Am einfachsten starten Sie eine Aktivität, die dem oben beschriebenen AR-erforderlichen Muster folgt.

Einhaltung der Datenschutzanforderungen

Achte darauf, dass deine App den Anforderungen an den Datenschutz für Nutzer von ARCore entspricht.

Weitere Informationen

Lesen Sie den Code und die Kommentare in der Beispiel-App sowie die C API-Referenz.