API Geospatial را برای برنامه اندروید خود فعال کنید (Kotlin/Java)

تنظیمات برنامه خود را طوری پیکربندی کنید که بتواند از Geospatial API استفاده کند.

پیش نیازها

قبل از ادامه، مطمئن شوید که مفاهیم اساسی AR و نحوه پیکربندی یک جلسه ARCore را درک کرده اید.

نمونه برنامه و کد لبه

این ویدئو مراحل ساخت اپلیکیشنی را که داده‌های مکانی را نمایش می‌دهد و محتوا را با استفاده از Geospatial API در مکان‌های واقعی قرار می‌دهد، طی می‌کند.

همچنین می‌توانید مستندات Geospatial Codelab را برای همین مراحل دنبال کنید. برای اجرای برنامه نمونه ایجاد شده در ویدیو، ARCore Geospatial Quickstart را ببینید.

برای اطلاعات بیشتر در مورد Geospatial API به مقدمه Geospatial API مراجعه کنید.

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

مطمئن شوید که محیط توسعه شما مطابق با نیازهای ARCore SDK، همانطور که در Quickstart توضیح داده شده است.

ARCore API را فعال کنید

قبل از استفاده از Visual Positioning System (VPS) در برنامه خود، ابتدا باید ARCore API را در پروژه Google Cloud جدید یا موجود فعال کنید. این سرویس وظیفه میزبانی، ذخیره و رفع لنگرهای جغرافیایی را بر عهده دارد.

مجوز بدون کلید ترجیح داده می شود، اما مجوز کلید API نیز پشتیبانی می شود.

کتابخانه های مورد نیاز را به برنامه خود اضافه کنید

پس از مجاز کردن برنامه خود برای فراخوانی ARCore API، باید کتابخانه‌هایی را اضافه کنید تا ویژگی‌های Geospatial را در برنامه خود فعال کنید.

در فایل build.gradle برنامه‌تان، سرویس‌های Google Play را طوری تنظیم کنید که کتابخانه مکان سرویس‌های Play را شامل شود.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

قابلیت های Geospatial را در پیکربندی جلسه فعال کنید

قبل از ایجاد جلسه، GeospatialMode را در تنظیمات جلسه خود به ENABLED تغییر دهید:

جاوا

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

کاتلین

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

در حالی که حالت Geospatial روی ENABLED تنظیم شده است، برنامه مجاز است اطلاعات جغرافیایی را از سیستم موقعیت یابی بصری (VPS) به دست آورد.

از کاربر بخواهید اجازه استفاده از داده های دستگاه را بدهد

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

سازگاری دستگاه را بررسی کنید

همه دستگاه‌هایی که از ARCore پشتیبانی می‌کنند، از Geospatial API نیز پشتیبانی نمی‌کنند، همانطور که در شروع سریع توضیح داده شد.

برای بررسی سازگاری دستگاه کاربر، با Session.checkGeospatialModeSupported() تماس بگیرید. اگر این مقدار false را برگرداند، سعی نکنید جلسه را پیکربندی کنید (زیر)، زیرا انجام این کار یک UnsupportedConfigurationException ایجاد می کند.

از کاربر برای مجوزهای مکان در زمان اجرا بخواهید

برنامه شما باید مجوزهای مکان را در زمان اجرا درخواست کند .

برای استفاده از ARCore Geospatial API، برنامه شما باید مجوزهای اضافی زیر را ثبت کند:

• ACCESS_FINE_LOCATION برای تعیین دقیق مکان کاربر.

• ACCESS_COARSE_LOCATION برای تعیین غیر دقیق مکان کاربر و مطابقت با الزامات حریم خصوصی کاربر. با این حال، Geospatial API را نمی‌توان برای کار با مکان درشت پیکربندی کرد، و زمانی که کاربر این مجوز را تنظیم کرده باشد، درخواست‌های API با شکست مواجه می‌شوند. برای اطلاعات بیشتر به زیر مراجعه کنید.

• ACCESS_INTERNET برای تماس با سرویس ARCore Geospatial API.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

در دستگاه‌هایی که دارای Android نسخه ۱۲ یا بالاتر هستند، کاربران می‌توانند درخواست کنند که برنامه شما فقط به اطلاعات موقعیت مکانی تقریبی دسترسی داشته باشد. برای انطباق با این درخواست، برنامه شما باید مجوز ACCESS_COARSE_LOCATION را به همراه ACCESS_FINE_LOCATION پیکربندی کرده باشد، همانطور که در بالا نشان داده شده است. شما باید هر دو مجوز مکان را پیکربندی کنید .

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

در دسترس بودن Geospatial را در مکان فعلی دستگاه بررسی کنید

از آنجایی که Geospatial API از ترکیبی از VPS و GPS برای تعیین موقعیت جغرافیایی استفاده می کند، تا زمانی که دستگاه قادر به تعیین موقعیت مکانی خود باشد، API می تواند مورد استفاده قرار گیرد. در مناطقی با دقت GPS پایین، مانند فضاهای داخلی و محیط‌های شهری متراکم، API برای ایجاد حالت‌های با دقت بالا به پوشش VPS متکی است. در شرایط معمولی می توان انتظار داشت که VPS دقت موقعیتی تقریباً 5 متر و دقت چرخشی 5 درجه را ارائه دهد. از Session.checkVpsAvailabilityAsync() برای تعیین اینکه آیا یک مکان مشخص دارای پوشش VPS است یا خیر استفاده کنید.

Geospatial API همچنین در مناطقی که پوشش VPS ندارند قابل استفاده است. در محیط‌های بیرونی که موانع بالای سرشان کم است یا اصلاً وجود ندارد، GPS ممکن است برای ایجاد یک حالت با دقت بالا کافی باشد.

بعدش چی

• موقعیت جغرافیایی دوربین دستگاه را برای تعیین مکان دقیق دستگاه کاربر در دنیای واقعی بدست آورید .
• در دسترس بودن VPS را در مکان معین دستگاه بررسی کنید .