Android uygulamanızda artırılmış gerçekliği (AR) etkinleştirme

Yeni veya mevcut uygulamanızda artırılmış gerçeklik özelliklerini kullanmak için artırılmış gerçeklik özelliğini etkinleştirin.

Uygulamanızı Artırılmış Gerçeklik (AR) Zorunlu veya Artırılmış Gerçeklik (AR) İsteğe Bağlı olacak şekilde yapılandırın

Her bir cihazda yer açmak için tüm AR özellikleri, Play Store tarafından ayrı olarak güncellenen AR için Google Play Hizmetleri adlı bir uygulamada depolanır. AR özelliklerini kullanan Android uygulamaları, ARCore SDK'sını kullanarak AR için Google Play Hizmetleri ile iletişim kurar. AR özelliklerini destekleyen uygulamalar iki şekilde yapılandırılabilir: AR Zorunlu ve AR İsteğe Bağlı. Bu tanımlama, uygulamanın AR için Google Play Hizmetleri uygulamasıyla nasıl etkileşimde bulunduğunu belirler.

AR Tarafından Gerekli uygulamalar, ARCore olmadan çalışamaz. AR için Google Play Hizmetleri'nin yüklü olduğu, ARCore destekli bir cihaz gerekir.

  • Google Play Store, yalnızca AR Core gerektiren uygulamaları ARCore'u destekleyen cihazlarda kullanıma sunacaktır.
  • Kullanıcılar AR için Gerekli bir uygulamayı yüklediklerinde, Google Play Store AR için Google Play Hizmetleri'ni cihazlarına otomatik olarak yükler. Ancak, AR için Google Play Hizmetleri güncel değilse veya manuel olarak kaldırılmışsa uygulamanızın ek çalışma zamanı kontrolleri gerçekleştirmesi gerekir.

İsteğe bağlı artırılmış gerçeklik (AR) uygulamaları, mevcut işlevleri geliştirmek için ARCore'u kullanır. Yalnızca AR için Google Play Hizmetleri'nin yüklü olduğu, ARCore destekli cihazlarda etkinleştirilen isteğe bağlı AR özelliklerine sahiptir.

  • İsteğe bağlı AR uygulamaları, ARCore'u desteklemeyen cihazlara yüklenebilir ve bu cihazlarda çalıştırılabilir.
  • Kullanıcılar isteğe bağlı bir AR için Google Play Hizmetleri uygulamasını cihaza yüklediklerinde Google Play Store, AR için Google Play Hizmetleri'ni cihaza otomatik olarak yüklemez.
Artırılmış Gerçeklik (AR) GerekliArtırılmış Gerçeklik (AR) İsteğe Bağlı
Artırılmış gerçeklik (AR) özelliğinin kullanımı Uygulamanızın temel işlevselliği için ARCore'a ihtiyacı vardır. ARCore, uygulamanızın işlevselliğini artırır. Uygulamanız, ARCore desteği olmadan çalışabilir.
Play Store görünürlüğü Uygulamanız yalnızca ARCore'u destekleyen cihazların Play Store'unda listelenir. Uygulamanızda normal giriş prosedürleri uygulanmaktadır.
AR için Google Play Hizmetleri yükleme yöntemi Play Store, uygulamanızın yanı sıra AR için Google Play Hizmetleri'ni yükler. Uygulamanızda, ARCore'u indirip yüklemek için ArCoreApk.requestInstall() kullanılıyor.
Android minSdkVersion gereksinimleri Android 7.0 (API Düzeyi 24) Android 7.0 (API Düzeyi 24)
ARCore desteğini ve yükleme durumunu kontrol etmek için ArCoreApk.checkAvailability() veya ArCoreApk.checkAvailabilityAsync() kullanılmalıdır
AR için Google Play Hizmetleri'ni yüklemek üzere ArCoreApk.requestInstall() kullanılmalıdır

Uygulamanızı AR Zorunlu veya Artırılmış Gerçeklik (AR) İsteğe Bağlı hale getirmek için AndroidManifest.xml cihazınızı aşağıdaki girişleri içerecek şekilde güncelleyin:

Artırılmış Gerçeklik (AR) Gerekli

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

Artırılmış Gerçeklik (AR) İsteğe Bağlı

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

Ardından, uygulamanızın build.gradle değerini değiştirerek minSdkVersion değerini en az 24 olarak belirtin:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Derleme bağımlılıkları ekleme

ARCore'u Android Studio projenize eklemek için aşağıdakileri yapın:

  1. Projenizin build.gradle dosyasının Google'ın Maven deposunu içerdiğinden emin olun.

    allprojects {
    repositories {
        google()
        …
    }
}

  2. En son ARCore kitaplığını uygulamanızın build.gradle dosyasına bağımlılık olarak ekleyin.

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

Çalışma zamanı kontrolleri gerçekleştirme

Uygulamanızdaki artırılmış gerçeklik özelliklerinin sorunsuz bir şekilde çalıştığından emin olmak için çalışma zamanı sırasında aşağıdakileri uygulayın.

ARCore'un desteklenip desteklenmediğini kontrol etme

Hem AR Zorunlu hem de AR İsteğe bağlı uygulamalar, mevcut cihazın ARCore'u destekleyip desteklemediğini belirlemek için ArCoreApk.checkAvailability() veya ArCoreApk.checkAvailabilityAsync() kullanmalıdır. ARCore'u desteklemeyen cihazlarda, uygulamalar AR ile ilgili işlevleri devre dışı bırakmalı ve ilişkili kullanıcı arayüzü öğelerini gizlemelidir.

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);
    }
  });
}
AR için Google Play Hizmetleri, AR için Gerekli uygulamanızla birlikte yüklü olsa da, desteklenmeyen cihazların kullanıcıları bu uygulamayı harici bir kaynaktan yükleyebilir. ARCore desteğini kontrol etmek için ArCoreApk.checkAvailability() veya ArCoreApk.checkAvailabilityAsync() aracını kullanmak tutarlı bir deneyim sağlar.

ArCoreApk.checkAvailability() uygulamasının, cihazın ARCore'u destekleyip desteklemediğini belirlemek için ağ kaynaklarını sorgulaması gerekebilir. Bu süre boyunca UNKNOWN_CHECKING değerini döndürecektir. Algılanan gecikmeyi ve pop-in'i azaltmak amacıyla uygulamalar, sorguyu başlatmak için yaşam döngüsünün başlarında ArCoreApk.checkAvailability()'i çağırarak döndürülen değeri yoksaymalıdır. Bu şekilde, AR girişi yapan bir kullanıcı arayüzü öğesi görüntülenebileceği zaman önbelleğe alınmış bir sonuç hemen kullanılabilir hale gelir.

AR için Google Play Hizmetleri'nin yüklü olup olmadığını kontrol etme

Hem AR Zorunlu hem de AR İsteğe bağlı uygulamalar, AR için Google Play Hizmetleri'nin uyumlu bir sürümünün yüklü olup olmadığını kontrol etmek ve gerekli tüm ARCore cihaz profili verilerinin indirildiğinden emin olmak amacıyla, ARCore oturumu oluşturulmadan önce ArCoreApk.requestInstall()'ı çağırmalıdır.

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

Kamera izni iste

Artırılmış Gerçeklik (AR) İsteğe Bağlı ve Artırılmış Gerçeklik (AR) Gerekli uygulamaları, AR Oturumu oluşturmadan önce kamera izninin verildiğinden emin olmalıdır.

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

  …
}

Artırılmış gerçeklik etkinliğiniz onRequestPermissionsResult()'i de uygulamalıdır.

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

Kullanıcı Gizliliği Şartlarına Uyma

Uygulamanızı Play Store'da yayınlamak için uygulamanızın ARCore'un Kullanıcı Gizliliği Şartları'na uyduğundan emin olun.

Sonraki adımlar