Android NDK uygulamanızda artırılmış gerçekliği etkinleştirme

Artırılmış gerçeklik özelliklerini yeni veya mevcut uygulamanızda kullanmak için AR'yi etkinleştirin.

Uygulamanızı AR Zorunlu veya AR İsteğe Bağlı olacak şekilde yapılandırın

Her bir cihazda alandan tasarruf etmek amacıyla, 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 bir uygulama iki şekilde yapılandırılabilir: AR Zorunlu ve İ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 Zorunlu uygulamaları, ARCore olmadan çalışamaz. AR için Google Play Hizmetleri'nin yüklü olduğu, ARCore destekli bir cihaz gerektirir.

Google Play Store, ARCore uygulamaları yalnızca 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'nin eski olması veya yüklemesinin manuel olarak kaldırılmış olması durumunda uygulamanızın yine de 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üklenip çalıştırılabilir.
Kullanıcılar isteğe bağlı bir AR uygulaması yüklediğinde Google Play Store, cihaza AR için Google Play Hizmetleri'ni otomatik olarak yüklemez.

	Artırılmış Gerçeklik (AR) Gerekli	Artırılmış Gerçeklik (AR) İsteğe Bağlı
Artırılmış Gerçeklik (AR) Özelliğinin kullanımı	Uygulamanızın temel işlevi için ARCore uygulaması gereklidir.	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 cihazlardaki Play Store'da listelenir.	Uygulamanızda normal giriş prosedürleri kullanılıyor.
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ız, ARCore'u indirip yüklemek için `ArCoreApk.requestInstall()` kullanıyor.
Android `minSdkVersion` gereksinimleri	Android 7.0 (API Düzeyi 24)	Android 4.4 (API Düzeyi 19), ancak AR işlevlerinin çalıştırılması için en az Android 7.0 (API Düzeyi 24) gerekir
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 İsteğe Bağlı hale getirmek için AndroidManifest.xml öğenizi 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, minSdkVersion değerini en az 24 olarak belirtecek şekilde değiştirin:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Derleme bağımlılıkları ekleme

Projenizin build.gradle dosyasının Google'ın Maven deposunu içerdiğinden emin olun.
```
allprojects {
    repositories {
        google()
        …
    }
}
```
ARCore AAR dosyasından dahil edilen yerel kitaplıkları çıkarmak için modülünüzün build.gradle dosyasına bir özel görev ekleyin. Böylece, doğrudan bir C veya C++ projesinde bunlara referans verilebilir.
app/build dizininde, yerel kitaplıkların çıkarılacağı dizin için bir değişken tanımlayın.

Verileri ve ayıklama görevlerini saklamak için bir Gradle yapılandırması oluşturun.

/*
The ARCore AAR library contains native shared libraries that 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 }

Yerel kitaplıkları AAR dosyasından kopyalamak ve derleme bağımlılıklarına eklemek için bir görev oluşturun.

// Extracts the shared libraries from AARs in the native configuration
// 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)
    }
}

Konumları harici derleme araçlarına geçirmek için yerel derleme bayraklarını yapılandırın.

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

Hem Java hem de yerel kitaplıklar için bağımlılık ekleyin.

dependencies {
     ...
     // Add Java and native dependencies to the ARCore library.
     implementation 'com.google.ar:core:1.33.0'
     natives 'com.google.ar:core:1.33.0'
     ...
}

CMakeLists.txt içindeki yerel kitaplıklara başvurun.

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

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

Uygulamanızdaki AR özelliklerinin sorunsuz çalışmasını sağlamak için çalışma sırasında aşağıdakileri yapı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.

Android NDK uygulamaları, yerel C ARCore Session API'de uyumluluğu kontrol etmek ve yüklemeyi yönetmek için Java ArCoreApk sınıfını kullanabilir. Uygulamanızın yapısına bağlı olarak bu, çok sayıda hata işleme ve kullanıcı arayüzü etkileşimi nedeniyle ArCoreApk_ işlevlerini kullanmaktan daha kolay olabilir.

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 or enable the AR button.
  } else {
    // Hide or disable the AR button.
  }
}

AR için Google Play Hizmetleri, AR için Zorunlu uygulamanız ile birlikte yüklenmiş olsa da, desteklenmeyen cihazlara sahip kullanıcılar bu uygulamayı harici bir kaynaktan yükleyebilir. ARCore desteğini kontrol etmek için ArCoreApk_checkAvailability() veya ArCoreApk_checkAvailabilityAsync() 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 zarfında AR_AVAILABILITY_UNKNOWN_CHECKING değerini döndürecektir. Uygulamalar, algılanan gecikmeyi ve pop-in'i azaltmak amacıyla, döndürülen değeri yoksayarak sorguyu başlatmak için yaşam döngüsünün başlarında bir kez ArCoreApk_checkAvailability()'i çağırmalıdır. Bu şekilde, artırılmış gerçeklik (AR) giren bir kullanıcı arayüzü öğesi görüntülenirken ö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

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

// Tracks if an installation request has already been triggered.
bool install_requested_;

void nativeOnCreate() {
  // Do other setup here.

  install_requested_ = false;
}

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

    ArInstallStatus install_status;
    // Ensure that 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 the ARCore session.
  }

  // Normal onResume behavior.
}

Kullanıcı Gizlilik Şartlarına Uyma

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

Sonraki adımlar

ARCore oturumunu nasıl yapılandıracağınızı öğrenin.