AR را در برنامه Android NDK خود فعال کنید

AR را برای استفاده از ویژگی‌های واقعیت افزوده در برنامه جدید یا موجود خود فعال کنید.

برنامه خود را طوری پیکربندی کنید که AR مورد نیاز یا AR اختیاری باشد

برای صرفه جویی در فضا در هر دستگاه، همه ویژگی‌های AR در برنامه‌ای به نام Google Play Services for AR ذخیره می‌شوند که به‌طور جداگانه توسط فروشگاه Play به‌روزرسانی می‌شود. برنامه‌های Android که از ویژگی‌های واقعیت افزوده استفاده می‌کنند، با استفاده از ARCore SDK با Google Play Services for AR ارتباط برقرار می‌کنند. برنامه‌ای که از ویژگی‌های AR پشتیبانی می‌کند می‌تواند به دو صورت پیکربندی شود: AR مورد نیاز و AR اختیاری . این تعیین نحوه تعامل برنامه با برنامه Google Play Services for AR را تعیین می کند.

یک برنامه AR مورد نیاز نمی تواند بدون ARCore کار کند. به یک دستگاه پشتیبانی شده از ARCore نیاز دارد که خدمات Google Play را برای واقعیت افزوده نصب کرده باشد.

  • فروشگاه Google Play فقط برنامه‌های AR مورد نیاز را در دستگاه‌هایی که از ARCore پشتیبانی می‌کنند در دسترس قرار می‌دهد.
  • هنگامی که کاربران یک برنامه AR مورد نیاز را نصب می کنند، فروشگاه Google Play به طور خودکار خدمات Google Play برای AR را در دستگاه آنها نصب می کند. با این حال، در صورتی که Google Play Services for AR قدیمی باشد یا به صورت دستی حذف نصب شده باشد، برنامه شما همچنان باید بررسی های زمان اجرا اضافی را انجام دهد .

یک برنامه اختیاری AR از ARCore برای بهبود عملکرد موجود استفاده می کند. دارای ویژگی‌های AR اختیاری است که فقط در دستگاه‌های پشتیبانی‌شده ARCore که سرویس‌های Google Play برای AR را نصب کرده‌اند، فعال می‌شوند.

  • برنامه‌های اختیاری AR را می‌توان روی دستگاه‌هایی که از ARCore پشتیبانی نمی‌کنند نصب و اجرا کرد.
  • وقتی کاربران یک برنامه اختیاری AR را نصب می‌کنند، فروشگاه Google Play به‌طور خودکار خدمات Google Play برای AR را روی دستگاه نصب نمی‌کند .
AR مورد نیاز است AR اختیاری
استفاده از ویژگی AR برنامه شما برای عملکرد اولیه به ARCore نیاز دارد. ARCore عملکرد برنامه شما را افزایش می دهد. برنامه شما می‌تواند بدون پشتیبانی ARCore اجرا شود.
قابلیت مشاهده فروشگاه Play برنامه شما فقط در دستگاه‌هایی که از ARCore پشتیبانی می‌کنند در فروشگاه Play فهرست شده است. برنامه شما از رویه‌های فهرست‌بندی معمولی پیروی می‌کند.
روش نصب Google Play Services for AR Play Store خدمات Google Play for AR را در کنار برنامه شما نصب می کند. برنامه شما از ArCoreApk.requestInstall() برای دانلود و نصب ARCore استفاده می کند.
نیازمندی های اندروید minSdkVersion Android 7.0 (API سطح 24) Android 4.4 (API Level 19)، اگرچه اجرای هر عملکرد AR به حداقل Android 7.0 (API Level 24) نیاز دارد.
برای بررسی پشتیبانی ARCore و وضعیت نصب باید از ArCoreApk_checkAvailability() یا ArCoreApk_checkAvailabilityAsync() استفاده کنید
برای نصب سرویس‌های Google Play برای AR باید از ArCoreApk.requestInstall() استفاده کنید

برای اینکه برنامه شما AR مورد نیاز یا اختیاری باشد، AndroidManifest.xml خود را به‌روزرسانی کنید تا شامل ورودی‌های زیر باشد:

AR مورد نیاز است 

<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 اختیاری

<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. وابستگی ها را برای کتابخانه های جاوا و بومی اضافه کنید.

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

بررسی های زمان اجرا را انجام دهید

در طول زمان اجرا، موارد زیر را انجام دهید تا مطمئن شوید که ویژگی‌های AR در برنامه شما به خوبی اجرا می‌شوند.

بررسی کنید که آیا ARCore پشتیبانی می شود

هر دو برنامه AR Required و AR اختیاری باید از ArCoreApk_checkAvailability() یا ArCoreApk_checkAvailabilityAsync() برای تعیین اینکه آیا دستگاه فعلی از ARCore پشتیبانی می کند استفاده کنند. در دستگاه‌هایی که از 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.
  }
}
حتی اگر Google Play Services for AR در کنار برنامه AR مورد نیاز شما نصب شده است، کاربرانی که دستگاه‌های پشتیبانی‌نشده دارند ممکن است آن را از یک منبع خارجی نصب کنند. استفاده از ArCoreApk_checkAvailability() یا ArCoreApk_checkAvailabilityAsync() برای بررسی پشتیبانی از ARCore، یک تجربه ثابت را تضمین می کند.

ArCoreApk_checkAvailability() ممکن است برای تعیین اینکه آیا دستگاه از ARCore پشتیبانی می کند یا خیر، نیاز به جستجو در منابع شبکه داشته باشد. در این مدت، AR_AVAILABILITY_UNKNOWN_CHECKING برمی‌گردد. برای کاهش تأخیر درک شده و بازشو، برنامه ها باید یک بار در اوایل چرخه عمر خود ArCoreApk_checkAvailability() فراخوانی کنند تا پرس و جو را آغاز کند، بدون توجه به مقدار برگشتی. به این ترتیب، هنگامی که ممکن است یک عنصر UI ورودی AR نمایش داده شود، یک نتیجه ذخیره شده در حافظه پنهان بلافاصله در دسترس خواهد بود.

بررسی کنید که آیا Google Play Services for AR نصب شده است یا خیر

هر دو برنامه AR مورد نیاز و AR اختیاری باید قبل از ایجاد یک جلسه ARCore ArCoreApk.requestInstall() استفاده کنند تا بررسی کنند که آیا نسخه سازگار Google Play Services برای AR (هنوز) نصب شده است یا خیر و اطمینان حاصل شود که تمام داده های نمایه دستگاه 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 مطابقت دارد.

بعدش چی