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

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 7.0 (API سطح 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
     }
 }

افزودن وابستگی های ساخت

برای افزودن ARCore به پروژه Android Studio خود، موارد زیر را انجام دهید:

مطمئن شوید که فایل build.gradle پروژه شما دارای مخزن Maven Google است.
```
allprojects {
    repositories {
        google()
        …
    }
}
```
جدیدترین کتابخانه ARCore را به عنوان یک وابستگی در فایل build.gradle برنامه خود اضافه کنید.
```
dependencies {
    …
    implementation 'com.google.ar:core:1.33.0'
}
```

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

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

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

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

کاتلین

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

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

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

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

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