تفعيل ميزة "الواقع المعزّز" في تطبيق NDK على نظام التشغيل Android

يجب تفعيل ميزة "الواقع المعزّز" لاستخدام ميزات الواقع المعزّز في تطبيقك الجديد أو الحالي.

يجب ضبط تطبيقك ليكون "الواقع المعزّز" أو "الواقع المعزّز" اختياري.

ولتوفير مساحة على الأجهزة الفردية، يتم تخزين جميع ميزات الواقع المعزّز في تطبيق يُسمّى خدمات Google Play للواقع المعزّز يتم تحديثه بشكل منفصل من خلال "متجر Play". تتواصل تطبيقات Android التي تستخدم ميزات الواقع المعزّز مع "خدمات Google Play للواقع المعزّز" باستخدام ARCore SDK. يمكن ضبط التطبيق الذي يتوافق مع ميزات الواقع المعزّز بطريقتَين: الواقع المعزّز مطلوب والواقع المعزّز اختياري. يحدِّد هذا التصنيف كيفية تفاعل التطبيق مع "خدمات Google Play" لتطبيق الواقع المعزّز.

لا يمكن أن يعمل تطبيق الواقع المعزّز بدون ARCore. تتطلب جهازًا متوافقًا مع ARCore وقد تم تثبيت "خدمات Google Play للواقع المعزّز" عليه.

• سيوفّر "متجر Google Play" تطبيقات "الواقع المعزّز" فقط على الأجهزة التي تتوافق مع ARCore.
• عندما يثبِّت المستخدمون أحد "تطبيقات الواقع المعزّز المطلوبة"، سيثبّت "متجر Google Play" تلقائيًا "خدمات Google Play للواقع المعزّز" على أجهزتهم. على الرغم من ذلك، يجب على تطبيقك إجراء عمليات تحقّق إضافية في وقت التشغيل إذا كانت "خدمات Google Play للواقع المعزّز" قديمة أو إذا تم إلغاء تثبيتها يدويًا.

يستخدِم تطبيق AR Optional تطبيق ARCore لتحسين الوظائف الحالية. وتتضمّن ميزات الواقع المعزّز الاختيارية التي لا يتم تفعيلها إلا على الأجهزة المتوافقة مع ARCore والتي تم تثبيت "خدمات Google Play للواقع المعزّز" عليها.

• يمكن تثبيت تطبيقات الواقع المعزّز الاختيارية وتشغيلها على الأجهزة التي لا تتوافق مع ARCore.
• عندما يثبِّت المستخدمون تطبيق "الواقع المعزّز" الاختياري، لن يثبِّت "متجر Google Play" تلقائيًا "خدمات Google Play للواقع المعزّز" على الجهاز.

لجعل تطبيقك "الواقع المعزّز" مطلوب أو "الواقع المعزّز" اختياري، عليك تعديل AndroidManifest.xml لتضمين الإدخالات التالية:

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

بعد ذلك، عدِّل build.gradle لتطبيقك لتحديد minSdkVersion بقيمة 24 على الأقل:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

إضافة تبعيات الإصدار

1. تأكَّد من أنّ ملف build.gradle الخاص بمشروعك يتضمّن مستودع Maven من Google.

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. أضِف مهمة مخصّصة إلى ملف build.gradle في وحدتك لاستخراج المكتبات الأصلية المضمّنة من ملف ARCore AAR. بهذه الطريقة، يمكن الإشارة إليها مباشرة في مشروع C أو C++.

3. في دليل app/build، حدِّد متغيّرًا للدليل الذي سيتم استخراج المكتبات الأصلية إليه.

4. أنشِئ إعداد Gradle للاحتفاظ بالبيانات ومهام الاستخراج.

   /*
   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، وإضافتها إلى تبعيات الإصدار.

   // 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. يمكنك ضبط علامات الإصدار الأصلي لتمرير المواقع إلى أدوات الإصدار الخارجية.

   // 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. أضف التبعيات لكل من Java والمكتبات الأصلية.

   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.

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

تنفيذ عمليات التحقّق في وقت التشغيل

أثناء وقت التشغيل، يمكنك تنفيذ الإجراءات التالية لضمان عمل ميزات الواقع المعزّز في تطبيقك بسلاسة.

التحقّق ممّا إذا كان ARCore متوافقًا

قد يستخدم تطبيق Android NDK فئة Java ArCoreApk للتحقّق من التوافق وإدارة التثبيت في واجهة برمجة تطبيقات C ARCore Session API الأصلية. وبناءً على بنية تطبيقك، قد يكون ذلك أسهل من استخدام وظائف ArCoreApk_ نظرًا لحجم معالجة الأخطاء الكبير والتفاعل مع واجهة المستخدم الذي ينطوي عليه ذلك.

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() إلى طلب موارد الشبكة لتحديد ما إذا كان الجهاز متوافقًا مع ARCore. خلال هذه الفترة، سيتم عرض AR_AVAILABILITY_UNKNOWN_CHECKING. لتقليل وقت الاستجابة والظهور المنبثق الذي يتم رصده، يجب أن تطلب التطبيقات ArCoreApk_checkAvailability() مرة واحدة في بداية دورة طلبها لبدء طلب البحث، مع تجاهل القيمة المعروضة. وبهذه الطريقة، ستتوفر نتيجة مخبأة على الفور عندما يتم عرض عنصر واجهة مستخدم يدخل إلى الواقع المعزّز.

التحقّق من تثبيت "خدمات Google Play للواقع المعزّز"

يجب أن يتصل كل من تطبيق "الواقع المعزّز" وتطبيق "الواقع المعزّز" بـ ArCoreApk_requestInstall() قبل إنشاء جلسة ARCore للتحقّق مما إذا كان إصدار متوافق من "خدمات Google Play للواقع المعزّز" (لا يزال) مثبّتًا وللتأكّد من تنزيل جميع بيانات الملف الشخصي المطلوبة لجهاز ARCore.

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

الالتزام بمتطلبات خصوصية المستخدم

لنشر تطبيقك على "متجر Play"، يُرجى التأكّد من امتثال تطبيقك لمتطلبات خصوصية المستخدم في ARCore.

الخطوات التالية

• تعرَّف على كيفية ضبط جلسة ARCore.