Google berkomitmen untuk memajukan kesetaraan rasial bagi komunitas Kulit Hitam. Lihat bagaimana.

Aktifkan ARCore

Halaman ini menjelaskan cara mengaktifkan fungsionalitas ARCore di proyek Android Studio Anda. Untuk melakukan ini, Anda perlu:

  1. Pilih antara AR Diperlukan dan AR Opsional untuk aplikasi Anda
  2. Tambahkan entri AR yang Diperlukan atau AR Opsional ke manifes aplikasi Anda
  3. Tambahkan dependensi build ke proyek Anda
  4. Lakukan pemeriksaan waktu proses untuk memastikan bahwa:
    • Perangkat ini mendukung ARCore ,
    • Layanan Google Play untuk AR diinstal di atasnya,
    • Izin kamera telah diberikan.
  5. Pastikan aplikasi Anda mematuhi Persyaratan Privasi Pengguna ARCore

Memilih antara AR Wajib atau AR Opsional

Aplikasi yang mendukung fitur AR dapat dikonfigurasi dengan dua cara: AR Diperlukan dan AR Opsional .

Aplikasi yang Diperlukan AR tidak dapat berfungsi tanpa ARCore. Agar dapat digunakan, aplikasi yang Diperlukan AR memerlukan Perangkat yang Didukung ARCore yang memiliki Layanan Google Play untuk AR terpasang di dalamnya.

Aplikasi AR Opsional menggunakan ARCore untuk menambah fungsionalitas yang berbeda. Aplikasi AR Opsional memiliki fitur AR opsional, yang hanya diaktifkan di perangkat yang didukung ARCore yang telah menginstal Layanan Google Play untuk AR .

  • Aplikasi opsional AR dapat diinstal dan dijalankan di perangkat yang tidak mendukung ARCore.

  • Saat pengguna memasang aplikasi AR Opsional, Google Play Store tidak akan secara otomatis memasang Layanan Google Play untuk AR dengan aplikasi tersebut.

AR Diperlukan AR Opsional
Penggunaan Fitur AR Aplikasi Anda membutuhkan ARCore untuk fungsionalitas dasar. ARCore menambah fungsionalitas aplikasi Anda. Aplikasi Anda dapat berjalan tanpa dukungan ARCore.
Visibilitas Play Store Aplikasi Anda hanya terdaftar di Play Store pada perangkat dengan dukungan ARCore. Aplikasi Anda mengikuti prosedur pencantuman normal .
Layanan Google Play untuk metode instalasi AR Play Store menginstal Layanan Google Play untuk AR bersama aplikasi Anda. Aplikasi Anda menggunakan ArCoreApk.requestInstall() untuk mendownload dan menginstal ARCore.
Persyaratan minSdkVersion Android Android 7.0 (API Level 24) Android 4.0 (API Level 14)
Harus menggunakan ArCoreApk.checkAvailability() untuk memeriksa dukungan ARCore dan status penginstalan
Harus menggunakan ArCoreApk.requestInstall() untuk menginstal Layanan Google Play untuk AR

Untuk informasi lebih lanjut, lihat Menerbitkan Aplikasi AR di Google Play Store .

Menambahkan entri ke manifes aplikasi Anda

Ubah AndroidManifest.xml Anda untuk menyertakan entri berikut:

AR Diperlukan

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

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

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

Kemudian, pastikan bahwa aplikasi Anda memiliki setidaknya minSdkVersion diperlukan di build.gradle aplikasi Anda:

AR Diperlukan

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR Opsional

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

Tambahkan dependensi build

Untuk menambahkan ARCore ke proyek Android Studio Anda, lakukan langkah-langkah berikut:

  • Pastikan file build.gradle proyek Anda menyertakan repositori Maven Google:

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • Tambahkan pustaka ARCore terbaru sebagai dependensi dalam file build.gradle aplikasi Anda:

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

Lakukan pemeriksaan runtime

Periksa apakah ARCore didukung

Baik AR Diperlukan dan aplikasi Opsional AR harus menggunakan ArCoreApk.checkAvailability() untuk menentukan apakah perangkat saat ini mendukung ARCore. Pada perangkat yang tidak mendukung ARCore, aplikasi harus menonaktifkan fungsionalitas terkait AR dan menyembunyikan elemen UI terkait.

Jawa

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

Meskipun Layanan Google Play untuk AR diinstal bersama aplikasi yang Diperlukan AR, pengguna dengan perangkat yang tidak didukung dapat menginstalnya dari sumber eksternal. Menggunakan checkAvailability() untuk memeriksa dukungan ARCore memastikan pengalaman yang konsisten.

checkAvailability() mungkin perlu menanyakan sumber daya jaringan untuk menentukan apakah perangkat mendukung ARCore. Selama waktu ini, ini akan mengembalikan UNKNOWN_CHECKING . Untuk mengurangi latensi dan pop-in yang dirasakan, aplikasi harus memanggil checkAvailability() satu kali di awal siklus hidupnya untuk memulai kueri, mengabaikan nilai yang dikembalikan. Dengan cara ini, hasil yang di-cache akan segera tersedia ketika maybeEnableArButton() dipanggil.

Minta izin kamera

Aplikasi AR Opsional dan AR yang Diperlukan harus memastikan bahwa izin kamera telah diberikan sebelum membuat Sesi AR. Contoh hello_ar_java menyertakan kelas CameraPermissionHelper yang bisa disalin ke dalam proyek Anda dan dipanggil dari metode onResume() aktivitas AR Anda:

Jawa

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

  …
}

Aktivitas AR Anda juga harus mengimplementasikan onRequestPermissionsResult() , seperti yang terlihat di HelloArActivity :

Jawa

@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()
  }
}

Periksa apakah Layanan Google Play untuk AR diinstal

Untuk memeriksa apakah versi Layanan Google Play yang kompatibel untuk AR (masih) terpasang, dan untuk memastikan bahwa semua data profil perangkat ARCore yang diperlukan telah diunduh, aplikasi AR yang Diperlukan dan AR Opsional harus memanggil ArCoreApk.requestInstall() sebelum membuat ARCore sidang. Ini meminta pengguna untuk menginstal atau mengupdate ARCore jika diperlukan, dan memastikan bahwa data profil perangkat ARCore yang diperlukan didownload.

Jawa

// requestInstall(Activity, true) will triggers 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.
  }
  …
}

Kepatuhan dengan Persyaratan Privasi Pengguna

Pastikan aplikasi Anda mematuhi Persyaratan Privasi Pengguna ARCore.

Langkah selanjutnya