راه‌اندازی Geospatial API در برنامه

دستگاه‌های XR واجدشرایط

این راهنمایی به شما کمک می‌کند برای این نوع دستگاه‌های واقعیت گسترده تجربه بسازید.

آشنایی با انواع دستگاه‌های XR →

عینک واقعیت گسترده سیمی

عینک
نمایشگردار و صوتی

آشنایی با انواع دستگاه‌های XR →

برای استفاده از Geospatial API در برنامه‌تان، برنامه شما باید برای دسترسی به ARCore API در Google Cloud راه‌اندازی شده باشد. این میانای برنامه‌سازی کاربردی حاوی سرویس موقعیت‌یابی بصری است که بااستفاده از داده‌های «نمای خیابان Google» موقعیت‌یابی دقیقی ارائه می‌دهد.

این راهنما به شما کمک می‌کند پروژه Google Cloud راه‌اندازی کنید که API و روش‌های مجوزدهی صحیح را برای دسترسی به API فعال کرده باشد.

راه‌اندازی پروژه Google Cloud یا استفاده از پروژه موجود

اگر پروژه Google Cloud موجودی دارید، آن را انتخاب کنید.

رفتن به انتخابگر پروژه

اگر پروژه موجودی ندارید، پروژه‌ای ایجاد کنید.

ایجاد کردن پروژه جدید

فعال کردن ARCore API

برای استفاده از ARCore API، باید آن را در پروژه‌تان فعال کنید.

فعال کردن ARCore API

راه‌اندازی مجوز برای Google Cloud

برنامه Android می‌تواند بااستفاده از دو روش مختلف درستی‌سنجی با ARCore API ارتباط برقرار کند: درستی‌سنجی بدون کلید (OAuth 2.0) که روش توصیه‌شده است، و درستی‌سنجی با کلید API:

• مجوزدهی بدون کلید از ترکیبی از نام بسته برنامه و اثر انگشت کلید امضا برای مجوزدهی به برنامه شما استفاده می‌کند.

• کلید میانای برنامه‌سازی کاربردی رشته‌ای است که پروژه Google Cloud را شناسایی می‌کند. کلیدهای میانای API معمولاً امن درنظر گرفته نمی‌شوند زیرا معمولاً برای کارخواه‌ها قابل‌دسترسی هستند. برای برقراری ارتباط با ARCore API، استفاده از مجوز «بدون کلید» را درنظر بگیرید.

مجوز بدون کلید

برای صدور مجوز برای برنامه‌تان بااستفاده از اصالت‌سنجی بدون کلید، شناسه‌های کارخواه OAuth 2.0 ایجاد کنید.

1. در Google Cloud، به صفحه اعتبارنامه‌ها بروید.

   رفتن به «اطلاعات کاربری»

2. روی ایجاد اطلاعات کاربری کلیک کنید، سپس شناسه کارخواه OAuth را از منو انتخاب کنید.

3. فیلدهای الزامی را به‌صورت زیر پر کنید:

   • نوع برنامه: Android را انتخاب کنید.
   • نام بسته: از نام بسته همان‌طور که در AndroidManifest.xml شما اعلام شده است استفاده کنید.
   • اثر انگشت گواهینامه SHA-1: اثر انگشت گواهینامه SHA-1 را بااستفاده از دستورالعمل‌های موجود در اصالت‌سنجی کارخواه دریافت کنید.

4. ایجاد را فشار دهید.

مهم: امضا کردن برنامه با کلیدهای امضای مختلف رایج است. باید برای هر کلید امضایی که قصد دارید استفاده کنید، یک «شناسه کارخواه» ایجاد کنید. معمولاً این کلیدها شامل کلید امضای اشکال‌زدایی و کلید(های) امضای نسخه پخش است. اگر صدور مجوز ناموفق بود، راهنمای عیب‌یابی را ببینید.

کلید میانای برنامه‌سازی کاربردی

با دنبال کردن این مراحل، کلید میانای برنامه‌سازی کاربردی را از «کنسول Google Cloud» ایجاد کنید:

1. در کنسول Google Cloud، به صفحه اعتبارنامه‌ها بروید:

   رفتن به «اطلاعات کاربری»

2. روی ایجاد اطلاعات کاربری کلیک کنید، سپس کلید میانای API را از منو انتخاب کنید.

3. «محدودیت میانای برنامه‌سازی کاربردی» را برای میانای برنامه‌سازی کاربردی ARCore اضافه کنید. برای اطلاعات بیشتر، به اعمال محدودیت‌های کلید API مراجعه کنید.

4. روی ایجاد کردن کلیک کنید. کادر گفتگوی کلید میانای API ایجاد شد رشته مربوط به کلید جدیداً ایجادشده را نمایش می‌دهد.

در Android Studio، کلید API جدید را به پروژه‌تان اضافه کنید. کلید میانای برنامه‌سازی کاربردی را در عنصر <meta-data> در عنصر <application> در AndroidManifest.xml برنامه‌تان قرار دهید:

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

درخواست اجازه‌های لازم

برای استفاده از Geospatial API در ARCore با Jetpack XR، برنامه‌تان باید اجازه‌های زمان اجرای زیر را درخواست کند:

• ACCESS_FINE_LOCATION: برای تعیین مکان دقیق کاربر لازم است.

در دستگاه‌های همراه، Geospatial API به اجازه‌های زیر نیز نیاز دارد:

• android.permission.CAMERA: برای دسترسی به دوربین دستگاه لازم است.
• android.permission.INTERNET: برای برقراری ارتباط با سرویس‌های Google Cloud لازم است.

دسترسی به جلسه

دسترسی به اطلاعات جغرافیایی ازطریق Jetpack XR Runtime Session، که برنامه شما باید ایجاد کند.

پیکربندی جلسه

میانای برنامه‌سازی کاربردی Geospatial به‌طور پیش‌فرض در جلسه‌های واقعیت گسترده فعال نیست. برنامه شما باید با پیکربندی GeospatialMode در Session، آن را صریحاً فعال کند. حالت‌های زیر دردسترس است:

• GeospatialMode.SPATIAL: Geospatial API فعال است. Geospatial API از داده‌های سامانه موقعیت‌یابی بصری (VPS)، سامانه موقعیت‌یابی جهانی (GPS)، و حسگرهای حرکتی دستگاه برای تعیین وضعیت جغرافیایی دستگاه استفاده می‌کند. این حالت در دستگاه‌های «افزاردید هوشمند» دردسترس نیست.
• GeospatialMode.INERTIAL: Geospatial API در حالت کم‌مصرف فعال است. Geospatial API فقط از GPS و حسگرهای حرکتی دستگاه برای تعیین وضعیت جغرافیایی دستگاه استفاده می‌کند. این حالت فقط در دستگاه‌های «افزاردید هوشمند» دردسترس است.
• GeospatialMode.DISABLED: Geospatial API غیرفعال است؛ هنگام انتقال از حالت دیگر به این حالت، Geospatial API همه منابع کسب‌شده را آزاد می‌کند و ردیابی را متوقف می‌کند.

همه دستگاه‌ها از همه حالت‌های Geospatial پشتیبانی نمی‌کنند. برای اطلاعات بیشتر، به GeospatialMode مراجعه کنید. از XrDevice.isGeospatialSupported برای اینکه آیا GeospatialMode داده‌شده پشتیبانی می‌شود یا نه استفاده کنید.

نمونه کد زیر نشان می‌دهد که چگونه می‌توان بااستفاده از Session.configure، GeospatialMode را تنظیم کرد.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

پیام‌واره به کاربر برای اجازه دادن به استفاده از داده‌های دستگاه

برنامه‌هایی که از Geospatial API با ARCore برای Jetpack XR استفاده می‌کنند باید پیام‌واره‌ای به کاربر نشان دهند تا استفاده از داده‌های دستگاهش را تأیید و مجاز کند. برای اطلاعات بیشتر، الزامات حریم خصوصی کاربر را ببینید.

استفاده از شیء Geospatial

پس‌از پیکربندی جلسه، شیء Geospatial را بااستفاده از Geospatial.getInstance دریافت کنید. فقط زمانی از شیء Geospatial استفاده کنید که وضعیت آن GeospatialTrackingState.RUNNING باشد.

نمونه کدهای زیر نحوه نظارت بر وضعیت «جغرافیایی-فضایی» را بااستفاده از Geospatial.state نشان می‌دهند.

Compose XR

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

SceneCore

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

توجه: اگر شیء GeospatialTrackingState هرگز GeospatialTrackingState.RUNNING نشد، برای راه‌حل‌های احتمالی به راهنمای عیب‌یابی مراجعه کنید.

آشنایی با مقادیر دقت

وقتی Geospatial API فعال باشد، سه مقدار دقت ارائه می‌دهد: دقت افقی، عمودی، و جهت‌یابی. این مقادیر دقت درطول زمان به‌روزرسانی می‌شوند و با به‌دست آمدن داده‌های بیشتر می‌توانند دقیق‌تر شوند. مقادیر بزرگ‌تر نشان‌دهنده دقت پایین‌تر است و به‌عنوان شعاع سطح اطمینان ۶۸٪ تعریف می‌شود. به عبارت دیگر، ۶۸٪ احتمال دارد که مقدار واقعی در شعاع مشخص‌شده از مقدار تخمینی باشد.

برای دریافت مقادیر دقت فعلی، از Geospatial.State.horizontalAccuracy، verticalAccuracy، و orientationYawAccuracy استفاده کنید.

ممکن است برنامه شما برای عملکرد صحیح به سطح خاصی از دقت نیاز داشته باشد. برای مثال، ممکن است برنامه شما بخواهد تا زمانی که دقت افقی کمتر از ۵ متر شود، برای ارائه محتوای مجازی صبر کند. برای افزایش احتمال به‌دست آوردن داده‌های با دقت بالاتر، برنامه‌تان باید به کاربران دستور دهد به اطراف خود نگاه کنند، ترجیحاً به ساختمان‌ها یا ویژگی‌های دیگری با جزئیات بصری بالا که در Google Street View وجود دارند. از Geospatial.checkVpsAvailability برای تعیین اینکه آیا VPS در مکان داده‌شده دردسترس است یا نه استفاده کنید.

قدم بعدی چیست

وقتی Geospatial API به‌درستی در برنامه‌تان راه‌اندازی شده باشد، برنامه‌تان می‌تواند کارهای زیر را انجام دهد:

• تبدیل بین حالت‌های محلی دستگاه و حالت‌های Geospatial،
• پرداز زدن محتوا در حالت‌های «زمین‌مکانی»