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

اضبط إعدادات تطبيقك بحيث يمكنه استخدام Geospatial API.

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

احرص على فهم مفاهيم الواقع المعزّز الأساسية وكيفية ضبط جلسة ARCore قبل المتابعة.

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

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

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

يمكنك الاطّلاع على مقدمة إلى Geospatial API للحصول على مزيد من المعلومات حول Geospatial API.

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

تأكَّد من أنّ بيئة التطوير تستوفي متطلبات حزمة تطوير البرامج (SDK) لـ ARCore، كما هو описан في البدء السريع.

تفعيل ARCore API

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

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

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

بعد تفويض تطبيقك للاتصال بواجهة برمجة التطبيقات ARCore API، عليك إضافة مكتبات ل تفعيل الميزات المكانية الجغرافية في تطبيقك.

في ملف 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، كما هو описан في الدليل السريع.

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

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

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

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

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

• ACCESS_COARSE_LOCATION لتحديد الموقع الجغرافي للمستخدم بشكل غير دقيق وللامتثال لمتطلبات خصوصية المستخدم. مع ذلك، لا يمكن ضبط واجهة برمجة التطبيقات Geospatial 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 12 أو إصدار أحدث، يمكن للمستخدمين طلب أن يحصل تطبيقك على معلومات الموقع الجغرافي التقريبي فقط. لاستيفاء هذا الطلب، يجب أن يكون إذن ACCESS_COARSE_LOCATION مفعّلاً في تطبيقك، بالإضافة إلى ACCESS_FINE_LOCATION، كما هو موضّح أعلاه. يجب ضبط كلا الإذنَين لتحديد الموقع الجغرافي.

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

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

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

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

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

• الحصول على معلومات وضع كاميرا الجهاز المتعلّقة بالموقع الجغرافي لتحديد الموقع الجغرافي الدقيق لجهاز المستخدم في العالم الحقيقي
• التحقّق من توفّر الخادم الظاهري في الموقع الجغرافي المحدّد للجهاز