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

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

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

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

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

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

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

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

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

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

تفعيل واجهة برمجة تطبيقات ARCore

قبل استخدام نظام تحديد المواقع المرئي (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 بضبط نفسها إذا كان تطبيقك يمنحها الموقع الجغرافي التقريبي فقط. لا يمكن لتطبيقك استخدام واجهة برمجة التطبيقات Geospatial API مع الموقع الجغرافي التقريبي.

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

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

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

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