تفعيل واجهة برمجة التطبيقات Geospatial API لتطبيق Android (Kotlin/Java)

اضبط إعدادات تطبيقك ليتمكّن من استخدام Geospatial API.

المتطلبات الأساسية

قبل المتابعة، تأكد من فهم مفاهيم الواقع المعزّز الأساسية وكيفية ضبط جلسة ARCore.

نموذج التطبيق والدرس التطبيقي حول الترميز

يرشدك هذا الفيديو إلى خطوات إنشاء تطبيق يعرض البيانات الجيوفضائية ويضع محتوى في مواقع جغرافية حقيقية باستخدام واجهة برمجة التطبيقات الجغرافية المكانية.

يمكنك أيضًا اتّباع مستندات الدرس التطبيقي حول الترميز الجغرافي المكاني لمعرفة الخطوات نفسها. لتشغيل نموذج التطبيق الذي تم إنشاؤه في الفيديو، راجع دليل البدء السريع لـ ARCore Geospatial.

راجِع مقدمة عن واجهة برمجة التطبيقات الجغرافية المكانية للحصول على مزيد من المعلومات حول واجهة برمجة التطبيقات الجيوفضائية.

إذا كنت حديث العهد بتطوير البرامج باستخدام ARCore، فراجع البدء للحصول على معلومات حول متطلبات البرامج والأجهزة والمتطلبات الأساسية والمعلومات الأخرى الخاصة بالأنظمة الأساسية التي تستخدمها.

تأكّد من أنّ بيئة التطوير تستوفي متطلبات حزمة ARCore SDK، كما هو موضّح في دليل البدء السريع.

تفعيل ARCore API

قبل استخدام نظام تحديد المواقع المرئي (VPS) في تطبيقك، يجب أولاً تفعيل ARCore API في مشروع جديد أو حالي على Google Cloud. وهذه الخدمة مسؤولة عن استضافة علامات الارتساء الجيوفضائية وتخزينها وحلها.

ويُفضَّل استخدام التفويض بدون مفتاح، ولكن يمكن أيضًا استخدام تفويض مفتاح واجهة برمجة التطبيقات.

إضافة المكتبات المطلوبة إلى تطبيقك

بعد السماح لتطبيقك بطلب واجهة برمجة التطبيقات ARCore، يجب إضافة مكتبات لتفعيل الميزات الجيوفضائية في تطبيقك.

في ملف 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)'
}

تفعيل الإمكانات الجيوفضائية في إعداد الجلسة

قبل إنشاء الجلسة، عليك تغيير GeospatialMode في إعدادات الجلسة إلى ENABLED:

Java

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

Kotlin

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

عند ضبط الوضع الجيوفضائي على ENABLED، يتم السماح للتطبيق بالحصول على المعلومات الجغرافية من نظام تحديد المواقع المرئية (VPS).

طلب السماح باستخدام بيانات الجهاز

يجب أن تقدّم التطبيقات التي تستخدم واجهة برمجة التطبيقات ARCore Geospatial API للمستخدم رسالة تطلب منه الإقرار باستخدام البيانات من جهازه والسماح باستخدامه. راجع متطلبات خصوصية المستخدم للحصول على مزيد من المعلومات.

التحقّق من توافق الجهاز

لا تتوافق بعض الأجهزة التي تدعم ARCore أيضًا مع واجهة برمجة التطبيقات Geospatial API، كما هو موضح في دليل quickstart.

للتحقّق من توافق جهاز المستخدم، يُرجى الاتصال بالرقم Session.checkGeospatialModeSupported(). وإذا عرض هذا الخطأ "خطأ"، لا تحاول ضبط الجلسة (أدناه)، لأنّ القيام بذلك سيؤدي إلى إنشاء UnsupportedConfigurationException.

طلب أذونات تحديد الموقع الجغرافي في وقت التشغيل من المستخدم

يجب أن يطلب تطبيقك أذونات تحديد الموقع الجغرافي في وقت التشغيل.

لاستخدام واجهة برمجة التطبيقات ARCore Geospatial API، يحتاج تطبيقك إلى تسجيل الأذونات الإضافية التالية:

  • ACCESS_FINE_LOCATION لتحديد الموقع الجغرافي للمستخدم بدقة.

  • ACCESS_COARSE_LOCATION للتحديد غير الدقيق لموقع المستخدم الجغرافي والامتثال لمتطلبات خصوصية المستخدم. ومع ذلك، لا يمكن ضبط واجهة برمجة التطبيقات Geospatial API لتعمل مع الموقع التقريبي، ولن يتم تنفيذ طلبات البيانات من واجهة برمجة التطبيقات إلا بعد ضبط المستخدم لهذا الإذن. انظر أدناه للاطّلاع على مزيد من المعلومات.

  • ACCESS_INTERNET للتواصل مع خدمة واجهة برمجة التطبيقات ARCore Geospatial

<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>

على الأجهزة التي تعمل بالإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث، يمكن للمستخدمين طلب الوصول إلى معلومات الموقع الجغرافي التقريبي فقط لتطبيقك. لتلبية هذا الطلب، يجب أن يتم ضبط إذن ACCESS_COARSE_LOCATION في تطبيقك، بالإضافة إلى ACCESS_FINE_LOCATION، كما هو موضّح أعلاه. يجب ضبط إذنَي تحديد الموقع الجغرافي.

ومع ذلك، عندما يحدد المستخدمون الموقع التقريبي، فإن ذلك يمنع واجهة برمجة التطبيقات الجيوفضائية من الحصول على الموقع الدقيق الذي تطلبه. لن تسمح الخدمة الجغرافية المكانية بتهيئة نفسها إذا كان تطبيقك يعطيه الموقع التقريبي فقط. لا يمكن لتطبيقك استخدام واجهة برمجة التطبيقات Geospatial API مع الموقع الجغرافي التقريبي.

التحقّق من مدى توفّر المواقع الجغرافية المكانية في الموقع الجغرافي الحالي للجهاز

بما أنّ واجهة برمجة التطبيقات Geospatial API تستخدم مزيجًا من VPS ونظام تحديد المواقع العالمي (GPS) لتحديد وضعية جيوفضائية، يمكن استخدام واجهة برمجة التطبيقات ما دام الجهاز قادرًا على تحديد موقعه الجغرافي. في المناطق ذات الدقة المنخفضة لنظام تحديد المواقع العالمي (GPS)، مثل المساحات الداخلية والبيئات الحضرية الكثيفة، ستعتمد واجهة برمجة التطبيقات على تغطية VPS لإنشاء وضعيات عالية الدقة. في ظل الظروف العادية، من المتوقع أن يوفر VPS دقة موضعية تبلغ 5 أمتار تقريبًا، ودقة دوران تبلغ 5 درجات. استخدِم Session.checkVpsAvailabilityAsync() لتحديد ما إذا كان موقع جغرافي معيّن تتوفّر فيه تغطية لبرنامج الشراء بالجملة (VPS).

يمكن أيضًا استخدام واجهة برمجة التطبيقات Geospatial API في المناطق التي لا تتوفر بها تغطية VPS. في البيئات الخارجية التي لا تحتوي على حواجز علوية أو بدونها، قد يكون نظام تحديد المواقع العالمي (GPS) كافيًا لإنشاء وضعية بدقة عالية.

الخطوات التالية