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

برای استفاده از ویژگی‌های واقعیت افزوده در برنامه جدید یا موجود خود، 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
     }
 }

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

برای اضافه کردن ARCore به پروژه اندروید استودیو خود، مراحل زیر را انجام دهید:

1. مطمئن شوید که فایل build.gradle پروژه شما شامل مخزن Maven گوگل است.

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. آخرین نسخه کتابخانه ARCore را به عنوان یک وابستگی در فایل build.gradle برنامه خود اضافه کنید.

   dependencies {
       …
       implementation 'com.google.ar:core:1.33.0'
   }
   

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

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

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

هر دو برنامه AR Required و AR Optional باید از ArCoreApk.checkAvailability() یا ArCoreApk.checkAvailabilityAsync() برای تعیین اینکه آیا دستگاه فعلی از ARCore پشتیبانی می‌کند یا خیر، استفاده کنند. در دستگاه‌هایی که از ARCore پشتیبانی نمی‌کنند، برنامه‌ها باید عملکردهای مرتبط با AR را غیرفعال کرده و عناصر رابط کاربری مرتبط را پنهان کنند.

کاتلین

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton()
  …
}

fun maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this) { availability ->
    if (availability.isSupported) {
      mArButton.visibility = View.VISIBLE
      mArButton.isEnabled = true
    } else { // The device is unsupported or unknown.
      mArButton.visibility = View.INVISIBLE
      mArButton.isEnabled = false
    }
  }
}

جاوا

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton();
  …
}

void maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this, availability -> {
    if (availability.isSupported()) {
      mArButton.setVisibility(View.VISIBLE);
      mArButton.setEnabled(true);
    } else { // The device is unsupported or unknown.
      mArButton.setVisibility(View.INVISIBLE);
      mArButton.setEnabled(false);
    }
  });
}

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

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

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

هر دو برنامه AR Required و AR Optional باید قبل از ایجاد یک جلسه ARCore ArCoreApk.requestInstall() استفاده کنند تا بررسی کنند که آیا نسخه سازگار Google Play Services برای AR (هنوز) نصب شده است یا خیر و اطمینان حاصل شود که تمام داده‌های پروفایل دستگاه ARCore مورد نیاز دانلود شده‌اند.

کاتلین

// requestInstall(Activity, true) will triggers installation of
// Google Play Services for AR if necessary.
var mUserRequestedInstall = true

override fun onResume() {
  super.onResume()

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      when (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        ArCoreApk.InstallStatus.INSTALLED -> {
          // Success: Safe to create the AR session.
          mSession = Session(this)
        }
        ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false
          return
        }
      }
    }
  } catch (e: UnavailableUserDeclinedInstallationException) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show()
    return
  } catch (…) {
    …
    return  // mSession remains null, since session creation has failed.
  }
  …
}

جاوا

// requestInstall(Activity, true) will trigger installation of
// Google Play Services for AR if necessary.
private boolean mUserRequestedInstall = true;

@Override
protected void onResume() {
  super.onResume();

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      switch (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        case INSTALLED:
          // Success: Safe to create the AR session.
          mSession = new Session(this);
          break;
        case INSTALL_REQUESTED:
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false;
          return;
      }
    }
  } catch (UnavailableUserDeclinedInstallationException e) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show();
    return;
  } catch (…) {
    …
    return;  // mSession remains null, since session creation has failed.
  }
  …
}

درخواست مجوز دوربین

هر دو برنامه AR Optional و AR Required باید قبل از ایجاد یک جلسه AR، اطمینان حاصل کنند که مجوز دوربین اعطا شده است.

کاتلین

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

جاوا

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

اکتیویتی AR شما باید onRequestPermissionsResult() را نیز پیاده‌سازی کند.

کاتلین

override fun onRequestPermissionsResult(
  requestCode: Int,
  permissions: Array<String>,
  results: IntArray
) {
  super.onRequestPermissionsResult(requestCode, permissions, results)
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
      .show()
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this)
    }
    finish()
  }
}

جاوا

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] results) {
  super.onRequestPermissionsResult(requestCode, permissions, results);
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
        .show();
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this);
    }
    finish();
  }
}

مطابق با الزامات حریم خصوصی کاربر

برای انتشار برنامه خود در فروشگاه Play، مطمئن شوید که برنامه شما با الزامات حریم خصوصی کاربر ARCore مطابقت دارد.

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

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