Mengaktifkan AR di aplikasi Android

Aktifkan AR untuk menggunakan fitur augmented reality di aplikasi baru atau yang sudah ada.

Mengonfigurasi aplikasi Anda menjadi AR Wajib atau AR Opsional

Untuk menghemat ruang di setiap perangkat, semua fitur AR disimpan dalam aplikasi yang disebut Layanan Google Play untuk AR yang diupdate secara terpisah oleh Play Store. Aplikasi Android yang menggunakan fitur AR berkomunikasi dengan Layanan Google Play untuk AR menggunakan ARCore SDK. Aplikasi yang mendukung fitur AR dapat dikonfigurasi dengan dua cara: AR Diperlukan dan AR Opsional. Penunjukan ini menentukan cara aplikasi berinteraksi dengan aplikasi Layanan Google Play untuk AR.

Aplikasi AR Wajib tidak dapat berfungsi tanpa ARCore. Aplikasi ini memerlukan perangkat yang didukung ARCore yang telah menginstal Layanan Google Play untuk AR.

  • Google Play Store hanya akan menyediakan aplikasi yang Memerlukan AR di perangkat yang mendukung ARCore.
  • Saat pengguna menginstal aplikasi yang Diperlukan untuk AR, Google Play Store akan otomatis menginstal Layanan Google Play untuk AR di perangkat mereka. Namun, aplikasi Anda tetap harus melakukan pemeriksaan runtime tambahan jika Layanan Google Play untuk AR tidak berlaku lagi atau telah di-uninstal secara manual.

Aplikasi AR Opsional menggunakan ARCore untuk meningkatkan fungsi yang ada. Aplikasi ini memiliki fitur AR opsional yang hanya diaktifkan di perangkat yang didukung ARCore dan telah menginstal Layanan Google Play untuk AR.

  • Aplikasi AR Optional dapat diinstal dan dijalankan di perangkat yang tidak mendukung ARCore.
  • Saat pengguna menginstal aplikasi Opsional AR, Google Play Store tidak akan otomatis menginstal Layanan Google Play untuk AR di perangkat.
AR DiperlukanAR Opsional
Penggunaan Fitur AR Aplikasi Anda membutuhkan ARCore untuk fungsionalitas dasar. ARCore meningkatkan fungsi aplikasi Anda. Aplikasi Anda dapat berjalan tanpa dukungan ARCore.
Visibilitas Play Store Aplikasi Anda hanya tercantum di Play Store pada perangkat yang mendukung ARCore. Aplikasi Anda mengikuti prosedur listingan normal.
Metode penginstalan Layanan Google Play untuk AR Play Store menginstal Layanan Google Play untuk AR bersama dengan aplikasi Anda. Aplikasi Anda menggunakan ArCoreApk.requestInstall() untuk mendownload dan menginstal ARCore.
Persyaratan minSdkVersion Android Android 7.0 (Level API 24) Android 4.4 (API Level 19), meskipun menjalankan semua fungsi AR memerlukan setidaknya Android 7.0 (API Level 24)
Harus menggunakan ArCoreApk.checkAvailability() atau ArCoreApk.checkAvailabilityAsync() untuk memeriksa dukungan ARCore dan status penginstalan
Harus menggunakan ArCoreApk.requestInstall() untuk menginstal Layanan Google Play untuk AR

Agar aplikasi Anda menjadi AR Wajib atau AR Opsional, update AndroidManifest.xml 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" />

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

Kemudian, ubah build.gradle aplikasi Anda untuk menentukan minSdkVersion minimal 24:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Menambahkan dependensi build

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

  1. Pastikan file build.gradle project Anda menyertakan repositori Maven Google.

    allprojects {
    repositories {
        google()
        …
    }
}

  2. Tambahkan library ARCore terbaru sebagai dependensi dalam file build.gradle aplikasi Anda.

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

Menjalankan pemeriksaan runtime

Selama runtime, lakukan hal berikut untuk memastikan fitur AR di aplikasi Anda berjalan lancar.

Memeriksa apakah ARCore didukung

Aplikasi AR Wajib dan AR Opsional harus menggunakan ArCoreApk.checkAvailability() atau ArCoreApk.checkAvailabilityAsync() untuk menentukan apakah perangkat saat ini mendukung ARCore. Di perangkat yang tidak mendukung ARCore, aplikasi harus menonaktifkan fungsi terkait AR dan menyembunyikan elemen UI terkait.

Kotlin

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

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

fun maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this) { availability ->
    if (availability.isSupported) {
      mArButton.visibility = View.VISIBLE
      mArButton.isEnabled = true
    } else { // The device is unsupported or unknown.
      mArButton.visibility = View.INVISIBLE
      mArButton.isEnabled = false
    }
  }
}

Java

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

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

void maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this, availability -> {
    if (availability.isSupported()) {
      mArButton.setVisibility(View.VISIBLE);
      mArButton.setEnabled(true);
    } else { // The device is unsupported or unknown.
      mArButton.setVisibility(View.INVISIBLE);
      mArButton.setEnabled(false);
    }
  });
}
Meskipun Layanan Google Play untuk AR diinstal bersama aplikasi AR Wajib, pengguna dengan perangkat yang tidak didukung dapat menginstalnya dari sumber eksternal. Menggunakan ArCoreApk.checkAvailability() atau ArCoreApk.checkAvailabilityAsync() untuk memeriksa dukungan ARCore akan memastikan pengalaman yang konsisten.

ArCoreApk.checkAvailability() mungkin perlu mengkueri resource jaringan untuk menentukan apakah perangkat mendukung ARCore. Selama waktu ini, tindakan ini akan menampilkan UNKNOWN_CHECKING. Untuk mengurangi latensi dan pop-in yang dirasakan, aplikasi harus memanggil ArCoreApk.checkAvailability() sekali di awal siklus prosesnya untuk memulai kueri, mengabaikan nilai yang ditampilkan. Dengan cara ini, hasil yang di-cache akan segera tersedia saat elemen UI yang masuk dengan AR mungkin ditampilkan.

Memeriksa apakah Layanan Google Play untuk AR telah diinstal

Aplikasi AR Diperlukan dan AR Optional harus digunakan ArCoreApk.requestInstall() sebelum membuat sesi ARCore untuk memeriksa apakah versi Layanan Google Play yang kompatibel untuk AR (masih) sudah diinstal dan untuk memastikan bahwa semua data profil perangkat ARCore yang diperlukan telah didownload.

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.
  }
  …
}

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.
  }
  …
}

Meminta izin kamera

Aplikasi AR Opsional dan AR Wajib harus memastikan bahwa izin kamera telah diberikan sebelum membuat Sesi AR.

Kotlin

override fun onResume() {
  super.onResume()

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

  …
}

Java

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

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

  …
}

Aktivitas AR Anda juga harus mengimplementasikan onRequestPermissionsResult().

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

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

Mematuhi Persyaratan Privasi Pengguna

Untuk memublikasikan aplikasi Anda di Play Store, pastikan aplikasi mematuhi persyaratan ARCore Persyaratan Privasi Pengguna.

Langkah selanjutnya