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

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

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

Tüm AR özellikleri, cihazlarda yer açmak için 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 AR İsteğe Bağlı. Bu tanım, uygulamanın AR için Google Play Hizmetleri uygulamasıyla nasıl etkileşimde bulunduğunu belirler.

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

• Google Play Store, AR'nin gerekli olduğu uygulamaları yalnızca ARCore'u destekleyen cihazlarda kullanıma sunar.
• Kullanıcılar AR için gerekli bir uygulama yüklediğinde 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ıldıysa uygulamanızın ek çalışma zamanında denetimler yapması gerekir.

AR İsteğe Bağlı uygulamalar, mevcut işlevleri iyileş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.

• AR İsteğe Bağlı uygulamaları, ARCore'u desteklemeyen cihazlara yüklenebilir ve çalıştırılabilir.
• Kullanıcılar AR için isteğe bağlı bir uygulama yüklediğinde Google Play Store, AR için Google Play Hizmetleri'ni cihaza otomatik olarak yüklemez.

Uygulamanızı AR Zorunlu veya AR İsteğe Bağlı yapmak için AndroidManifest.xml dosyanızı aşağıdaki girişleri içerecek şekilde güncelleyin:

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

<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 en az 24 olan bir minSdkVersion değerini belirtecek şekilde değiştirin:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Derleme bağımlılıkları ekleme

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

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. Dahil edilen yerel kitaplıkları ARCore AAR dosyasından çıkarmak için modülünüzün build.gradle dosyasına özel bir görev ekleyin. Bu sayede, doğrudan bir C veya C++ projesinde referans verilebilirler.

3. app/build dizininde, yerel kitaplıkların ayıklanacağı dizine bir değişken tanımlayın.

4. Verileri ve ayıklama görevlerini barındıracak 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 }
   

5. AAR dosyasından yerel kitaplıkları kopyalayacak bir görev oluşturun ve bu görevi derleme bağımlılıklarına ekleyin.

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

6. Yerleri harici derleme araçlarına iletecek şekilde yerel derleme işaretlerini 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"
       }
   }
   

7. Hem Java hem de yerel kitaplıklar için bağımlılıkları 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'
        ...
   }
   

8. CMakeLists.txt uygulamasındaki 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ı denetimleri gerçekleştirme

Uygulamanızdaki artırılmış gerçeklik özelliklerinin sorunsuz çalışmasını sağlamak için çalışma zamanı sırasında aşağıdaki işlemleri yapın.

ARCore'un desteklenip desteklenmediğini kontrol etme

Bir Android NDK uygulaması, yerel C ARCore Session API'sinde 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 yöntem, çok sayıda hata işleme ve kullanıcı arayüzü etkileşimi içerdiğinden 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.
  }
}

ArCoreApk_checkAvailability() uygulamasının, cihazın ARCore'u destekleyip desteklemediğini belirlemek için ağ kaynaklarını sorgulaması gerekebilir. Bu süre boyunca AR_AVAILABILITY_UNKNOWN_CHECKING döndürülür. Algılanan gecikmeyi ve pop-in'i azaltmak için uygulamaların, döndürülen değeri yoksayarak sorguyu başlatmak üzere yaşam döngüsünün başlarında bir kez ArCoreApk_checkAvailability() çağrısı yapması gerekir. Bu sayede, AR'ye giren bir kullanıcı arayüzü öğesi gösterilebileceğinde önbelleğe alınmış bir sonuç hemen kullanılabilir.

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

Hem AR'nin Zorunlu Olduğu hem de AR'nin İsteğe Bağlı Olduğu uygulamalar, AR için Google Play Hizmetleri'nin uyumlu bir sürümünün (hala) yüklü olup olmadığını kontrol etmek ve gerekli tüm ARCore cihaz profili verilerinin indirildiğinden emin olmak için ARCore oturumu oluşturmadan önce ArCoreApk.requestInstall() kullanmalı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 ARCore'un Kullanıcı Gizliliği Şartları'na uyduğundan emin olun.

Sırada ne var?

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