ARCore aktivieren

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

  1. Entscheiden Sie sich für Ihre App zwischen AR erforderlich und AR optional.
  2. App-Manifest für AR-erforderliche oder AR-optionale Einträge hinzufügen
  3. Build-Abhängigkeiten hinzufügen
  4. Führen Sie Laufzeitprüfungen durch, um:
    • Das Gerät unterstützt ARCore,
    • die Google Play-Dienste für AR installiert haben,
    • Die Kameraberechtigung wurde gewährt.
  5. Achte darauf, dass deine App den Anforderungen an den Datenschutz für Nutzer entspricht

Auswahl zwischen AR erforderlich oder AR optional

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

Eine App mit AR erforderlich kann nicht ohne ARCore verwendet werden. Damit eine AR-App verwendet werden kann, ist ein ARCore-unterstütztes Gerät erforderlich, auf dem die Google Play-Dienste für AR installiert ist.

Eine optionale App verwendet ARCore, um eine andere Funktion zu ergänzen Eine AR-optionale App hat optionale AR-Funktionen, die nur auf ARCore-fähigen Geräten aktiviert sind, auf denen die Google Play-Dienste für AR installiert sind.

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

AR erforderlichAR (optional)
Nutzung der AR-Funktion Für grundlegende Funktionen deiner App ist ARCore erforderlich. ARCore ergänzt die Funktionen deiner App. Ihre Anwendung kann ohne ARCore-Unterstützung ausgeführt werden.
Sichtbarkeit des Play Store Ihre App ist nur im Play Store auf Geräten mit ARCore-Unterstützung verfügbar. Für Ihre App werden die normalen Einträge angewendet.
Installationsmethode Google Play-Dienste für AR Im Play Store werden Google Play-Dienste für AR zusammen mit Ihrer App installiert. Deine App verwendet ArCoreApk.requestInstall(), um ARCore herunterzuladen und zu installieren.
Anforderungen für Android minSdkVersion Android 7.0 (API-Level 24) Android 4.0 (API-Level 14)
Sie müssen ArCoreApk.checkAvailability() verwenden, um den ARCore-Support und den Installationsstatus zu prüfen
Du musst ArCoreApk.requestInstall() verwenden, um Google Play-Dienste für AR zu installieren

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

Einträge in das Manifest der App einfügen

Ändern Sie den Wert für AndroidManifest.xml so, dass er die folgenden Einträge enthält:

AR erforderlich

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

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

AR (optional)

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

Prüfe dann, ob deine App mindestens die erforderliche minSdkVersion in den build.gradle-Apps hat:

AR erforderlich

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR (optional)

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

Build-Abhängigkeiten hinzufügen

Gehen Sie folgendermaßen vor, um Ihrem Android Studio-Projekt ARCore hinzuzufügen:

  • Vergewissere dich, dass deine build.gradle-Datei in deinem Projekt das Maven-Repository von Google enthält:

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • Füge die neueste ARCore-Bibliothek als Abhängigkeit in die Datei app's build.gradle ein:

    dependencies {
        …
        implementation 'com.google.ar:core:1.32.0'
    }
    

Laufzeitprüfungen durchführen

Prüfen, ob ARCore unterstützt wird

Sowohl mit AR erforderlich als auch mit AR optional kann mit ArCoreApk.checkAvailability() ermittelt werden, ob das aktuelle Gerät ARCore unterstützt. Auf Geräten, die ARCore nicht unterstützen, sollten Apps AR-bezogene Funktionen deaktivieren und die entsprechenden UI-Elemente ausblenden.

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton();
  …
}

void maybeEnableArButton() {
  ArCoreApk.Availability availability = ArCoreApk.getInstance().checkAvailability(this);
  if (availability.isTransient()) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    new Handler().postDelayed(new Runnable() {
      @Override
      public void run() {
        maybeEnableArButton();
      }
    }, 200);
  }
  if (availability.isSupported()) {
    mArButton.setVisibility(View.VISIBLE);
    mArButton.setEnabled(true);
  } else { // The device is unsupported or unknown.
    mArButton.setVisibility(View.INVISIBLE);
    mArButton.setEnabled(false);
  }
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton()
  …
}

fun maybeEnableArButton() {
  val availability = ArCoreApk.getInstance().checkAvailability(this)
  if (availability.isTransient) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    Handler().postDelayed({
      maybeEnableArButton()
    }, 200)
  }
  if (availability.isSupported) {
    mArButton.visibility = View.VISIBLE
    mArButton.isEnabled = true
  } else { // The device is unsupported or unknown.
    mArButton.visibility = View.INVISIBLE
    mArButton.isEnabled = false
  }
}

Obwohl Google Play-Dienste für AR zusammen mit deiner AR-erforderlichen App installiert ist, können Nutzer mit nicht unterstützten Geräten sie möglicherweise aus einer externen Quelle installieren. Mit checkAvailability() kannst du prüfen, ob ARCore-Unterstützung besteht.

checkAvailability() muss möglicherweise Netzwerkressourcen abfragen, um festzustellen, ob das Gerät ARCore unterstützt. Während dieser Zeit wird UNKNOWN_CHECKING zurückgegeben. Zur Reduzierung der wahrgenommenen Latenz und der Pop-up-Verbindung sollten Apps checkAvailability() früher in ihrem Lebenszyklus aufrufen, um die Abfrage zu starten und den zurückgegebenen Wert zu ignorieren. Auf diese Weise steht ein im Cache gespeichertes Ergebnis sofort zur Verfügung, wenn maybeEnableArButton() aufgerufen wird.

Kameraberechtigung anfordern

Sowohl bei optionalen als auch bei erforderlichen AR-Apps muss vor dem Erstellen einer AR-Sitzung sichergestellt sein, dass die Kameraberechtigung gewährt wurde. Das Beispiel hello_ar_java enthält eine CameraPermissionHelper-Klasse, die in Ihr Projekt kopiert und aus der onResume()-Methode von AR aufgerufen werden kann:

Java

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

Kotlin

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

In deiner AR-Aktivität muss auch onRequestPermissionsResult() implementiert sein, wie in HelloArActivity dargestellt:

Java

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] results) {
  super.onRequestPermissionsResult(requestCode, permissions, results);
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
        .show();
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this);
    }
    finish();
  }
}

Kotlin

override fun onRequestPermissionsResult(
  requestCode: Int,
  permissions: Array<String>,
  results: IntArray
) {
  super.onRequestPermissionsResult(requestCode, permissions, results)
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
      .show()
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this)
    }
    finish()
  }
}

Prüfen, ob Google Play-Dienste für AR installiert sind

Wenn du prüfen möchtest, ob eine kompatible Version der Google Play-Dienste für AR installiert ist, und ob du alle erforderlichen ARCore-Geräteprofildaten heruntergeladen hast, müssen sowohl für AR-erforderliche als auch für AR-optionale Apps ArCoreApk.requestInstall() aufgerufen werden, bevor eine ARCore-Sitzung erstellt werden kann. Dadurch wird der Nutzer aufgefordert, ARCore zu installieren oder zu aktualisieren, und es wird sichergestellt, dass die erforderlichen ARCore-Geräteprofildaten heruntergeladen werden.

Java

// requestInstall(Activity, true) will trigger installation of
// Google Play Services for AR if necessary.
private boolean mUserRequestedInstall = true;

@Override
protected void onResume() {
  super.onResume();

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      switch (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        case INSTALLED:
          // Success: Safe to create the AR session.
          mSession = new Session(this);
          break;
        case INSTALL_REQUESTED:
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false;
          return;
      }
    }
  } catch (UnavailableUserDeclinedInstallationException e) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show();
    return;
  } catch (…) {
    …
    return;  // mSession remains null, since session creation has failed.
  }
  …
}

Kotlin

// requestInstall(Activity, true) will triggers installation of
// Google Play Services for AR if necessary.
var mUserRequestedInstall = true

override fun onResume() {
  super.onResume()

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      when (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        ArCoreApk.InstallStatus.INSTALLED -> {
          // Success: Safe to create the AR session.
          mSession = Session(this)
        }
        ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false
          return
        }
      }
    }
  } catch (e: UnavailableUserDeclinedInstallationException) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show()
    return
  } catch (…) {
    …
    return  // mSession remains null, since session creation has failed.
  }
  …
}

Einhaltung der Datenschutzanforderungen

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

Weitere Informationen