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

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

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

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

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

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

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

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

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

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

تفعيل 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، الموضحة في البدء السريع.

للتحقق من توافق جهاز المستخدم، يُرجى الاتصال 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>

على الأجهزة التي تعمل بالإصدار 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) كافيًا لإنشاء وضعية بدقة عالية.

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