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

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

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

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

إذا كنت ترغب في تشغيل نموذج تطبيق يوضح الوظائف الموضحة هنا، فراجع ARCore Geospatial Quickstart for Android للغة Java. تتم كتابة نموذج التطبيق في Quickstart بلغة Java. عينات التعليمات البرمجية في هذا المستند هي لنفس الوظيفة المكتوبة بلغة C.

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

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

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

تفعيل 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:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

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

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

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

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

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

للتحقّق من توافق جهاز المستخدم، يُرجى الاتصال بالرقم ArSession_isGeospatialModeSupported(). إذا عرض هذا الخيار false، لا تحاول ضبط الجلسة (أدناه)، لأنّ ذلك سيؤدي إلى إبلاغ ArStatus عن AR_ERROR_UNSUPPORTED_CONFIGURATION.

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

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

لاستخدام واجهة برمجة التطبيقات 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 درجات. استخدِم ArSession_checkVpsAvailabilityAsync() لتحديد ما إذا كان موقع جغرافي معيّن تتوفّر فيه تغطية لبرنامج الشراء بالجملة (VPS).

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

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