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

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

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

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

إذا كنت ترغب في تشغيل نموذج تطبيق يوضح الوظائف الموضحة هنا، راجع ARCore Geospatial Quickstart لأجهزة Android لـ Java. تم كتابة نموذج التطبيق في "البدء السريع" بلغة Java. إنّ عينات التعليمات البرمجية في هذا المستند مخصّصة للوظيفة نفسها المكتوبة بلغة C.

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

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

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

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

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

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

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

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

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

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

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

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

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