این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

یک برنامه‌ی AR Required نمی‌تواند بدون ARCore کار کند. این برنامه به دستگاهی نیاز دارد که از ARCore پشتیبانی کند و سرویس‌های Google Play for AR را نصب کرده باشد.

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

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

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

	AR مورد نیاز است	AR اختیاری
استفاده از ویژگی AR	برنامه شما برای عملکرد اولیه به ARCore نیاز دارد.	ARCore عملکرد برنامه شما را افزایش می‌دهد. برنامه شما می‌تواند بدون پشتیبانی ARCore اجرا شود.
قابلیت مشاهده در فروشگاه پلی استور	برنامه شما فقط در دستگاه‌هایی که از ARCore پشتیبانی می‌کنند، در فروشگاه Play فهرست شده است.	برنامه شما از رویه‌های معمول فهرست‌بندی پیروی می‌کند.
روش نصب سرویس‌های گوگل پلی برای واقعیت افزوده	فروشگاه پلی، سرویس‌های گوگل پلی برای واقعیت افزوده را در کنار برنامه شما نصب می‌کند.	برنامه شما از `ArCoreApk.requestInstall()` برای دانلود و نصب ARCore استفاده می‌کند.
الزامات `minSdkVersion` اندروید	اندروید ۷.۰ (سطح API ۲۴)	اندروید ۴.۴ (API سطح ۱۹)، هرچند اجرای هرگونه قابلیت واقعیت افزوده حداقل به اندروید ۷.۰ (API سطح ۲۴) نیاز دارد.
برای بررسی پشتیبانی ARCore و وضعیت نصب، باید `ArCoreApk_checkAvailability()` یا `ArCoreApk_checkAvailabilityAsync()` استفاده کنید.
برای نصب سرویس‌های گوگل پلی برای واقعیت افزوده باید از `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
     }
 }

اضافه کردن وابستگی‌های ساخت

مطمئن شوید که فایل build.gradle پروژه شما شامل مخزن Maven گوگل است.
```
allprojects {
    repositories {
        google()
        …
    }
}
```
یک وظیفه سفارشی به فایل build.gradle ماژول خود اضافه کنید تا کتابخانه‌های بومی موجود در فایل ARCore AAR را استخراج کند. به این ترتیب، می‌توان آنها را مستقیماً در یک پروژه C یا C++ ارجاع داد.
در دایرکتوری app/build ، یک متغیر برای دایرکتوری که کتابخانه‌های بومی در آن استخراج می‌شوند، تعریف کنید.

یک پیکربندی 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 }

یک وظیفه ایجاد کنید تا کتابخانه‌های بومی را از فایل 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)
    }
}

پرچم‌های ساخت بومی را پیکربندی کنید تا مکان‌ها را به ابزارهای ساخت خارجی منتقل کنند.

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

وابستگی‌ها را برای کتابخانه‌های جاوا و بومی اضافه کنید.

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 ارجاع دهید.

# 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 Optional باید از ArCoreApk_checkAvailability() یا ArCoreApk_checkAvailabilityAsync() برای تعیین اینکه آیا دستگاه فعلی از ARCore پشتیبانی می‌کند یا خیر، استفاده کنند. در دستگاه‌هایی که از ARCore پشتیبانی نمی‌کنند، برنامه‌ها باید عملکردهای مرتبط با AR را غیرفعال کرده و عناصر رابط کاربری مرتبط را پنهان کنند.

یک برنامه اندروید NDK ممکن است از کلاس ArCoreApk جاوا برای بررسی سازگاری و مدیریت نصب در API جلسه ARCore بومی C استفاده کند. بسته به ساختار برنامه شما، این ممکن است به دلیل حجم زیاد مدیریت خطا و تعامل با رابط کاربری، آسان‌تر از استفاده از توابع 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.
  }
}

حتی اگر سرویس‌های گوگل پلی برای واقعیت افزوده در کنار برنامه AR Required شما نصب شده باشد، کاربرانی که دستگاه‌هایشان از این سرویس‌ها پشتیبانی نمی‌کند، ممکن است آن را از یک منبع خارجی نصب کنند. استفاده از ArCoreApk_checkAvailability() یا ArCoreApk_checkAvailabilityAsync() برای بررسی پشتیبانی از ARCore، یک تجربه پایدار را تضمین می‌کند.

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

بررسی کنید که آیا سرویس‌های Google Play برای واقعیت افزوده نصب شده‌اند یا خیر.

هر دو برنامه AR Required و AR Optional باید قبل از ایجاد یک جلسه 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 مطابقت دارد.

قدم بعدی چیست؟

یاد بگیرید که چگونه یک جلسه ARCore را پیکربندی کنید .

AR را در برنامه Android NDK خود فعال کنید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.