إعداد Geospatial API في تطبيقك

أجهزة XR المشمولة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة XR.
مزيد من المعلومات حول أنواع أجهزة XR →
نظارات سلكية بنظام الواقع الممتد
نظارات بشاشة عرض
وميزات صوتية
مزيد من المعلومات حول أنواع أجهزة XR →

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

يساعدك هذا الدليل في إعداد مشروع على السحابة الإلكترونية على Google Cloud تم فيه تفعيل واجهة برمجة التطبيقات وطرق التفويض الصحيحة للوصول إلى واجهة برمجة التطبيقات.

إعداد مشروع على Google Cloud أو استخدام مشروع حالي

إذا كان لديك مشروع حالي على Google Cloud، اختَره.

الانتقال إلى أداة اختيار المشاريع

إذا لم يكن لديك مشروع حالي، أنشِئ مشروعًا.

إنشاء مشروع جديد

تفعيل ARCore API

لاستخدام ARCore API، يجب تفعيلها في مشروعك.

تفعيل ARCore API

إعداد التفويض في Google Cloud

يمكن لتطبيق Android الاتصال بواجهة برمجة تطبيقات ARCore باستخدام طريقتين مختلفتين للتفويض: التفويض بدون مفتاح (OAuth 2.0)، وهي الطريقة المقترَحة، والتفويض باستخدام مفتاح واجهة برمجة التطبيقات:

  • تستخدم المصادقة بدون مفتاح مزيجًا من اسم حزمة التطبيق وبصمة إصبع مفتاح التوقيع لمصادقة تطبيقك.

  • مفتاح واجهة برمجة التطبيقات هو سلسلة تحدّد مشروعًا على Google Cloud. لا تُعتبر مفاتيح واجهة برمجة التطبيقات آمنة بشكل عام لأنّها تكون عادةً متاحة للعملاء. ننصحك باستخدام التفويض بدون مفتاح للتواصل مع واجهة برمجة التطبيقات ARCore API.

التفويض بدون مفتاح

للسماح لتطبيقك باستخدام المصادقة بدون مفتاح، أنشئ معرّفات عملاء OAuth 2.0.

  1. في Google Cloud، انتقِل إلى صفحة بيانات الاعتماد.

    الانتقال إلى "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد، ثم اختَر معرِّف عميل OAuth من القائمة.

  3. املأ الحقول المطلوبة على النحو التالي:

    • نوع التطبيق: اختَر Android.
    • اسم الحزمة: استخدِم اسم الحزمة كما هو موضّح في ملف AndroidManifest.xml.
    • الملف المرجعي لشهادة SHA-1: يمكنك الحصول على الملفات المرجعية لشهادة SHA-1 باتّباع التعليمات الواردة في مصادقة العميل.

  4. انقر على إنشاء.

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

أنشئ مفتاح واجهة برمجة التطبيقات من Google Cloud Console باتّباع الخطوات التالية:

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة بيانات الاعتماد:

    الانتقال إلى "بيانات الاعتماد"

  2. انقر على إنشاء بيانات الاعتماد، ثم اختَر مفتاح واجهة برمجة التطبيقات من القائمة.

  3. أضِف قيدًا على واجهة برمجة التطبيقات ARCore API. لمزيد من المعلومات، يُرجى الاطّلاع على تطبيق قيود مفتاح واجهة برمجة التطبيقات.

  4. انقر على إنشاء. يعرض مربّع الحوار تم إنشاء مفتاح واجهة برمجة التطبيقات السلسلة الخاصة بالمفتاح الذي تم إنشاؤه حديثًا.

في "استوديو Android"، أضِف مفتاح واجهة برمجة التطبيقات الجديد إلى مشروعك. أدرِج مفتاح واجهة برمجة التطبيقات في عنصر <meta-data> ضمن عنصر <application> في ملف AndroidManifest.xml الخاص بتطبيقك:

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

طلب الأذونات المطلوبة

لاستخدام Geospatial API في ARCore مع Jetpack XR، يحتاج تطبيقك إلى طلب أذونات التشغيل التالية:

على الأجهزة الجوّالة، تتطلّب Geospatial API أيضًا الأذونات التالية:

الوصول إلى جلسة

يمكنك الوصول إلى المعلومات الجغرافية المكانية من خلال بيئة التشغيل Jetpack XR Runtime Session، التي يجب أن ينشئها تطبيقك.

ضبط الجلسة

لا تكون Geospatial API مفعَّلة تلقائيًا في جلسات الواقع الممتد. يجب أن يفعّل تطبيقك هذه الميزة صراحةً من خلال ضبط GeospatialMode على Session. تتوفّر الأوضاع التالية:

  • GeospatialMode.SPATIAL: تم تفعيل Geospatial API. تستخدم Geospatial API نظام تحديد المواقع المرئي (VPS) وبيانات نظام تحديد المواقع العالمي (GPS) وأجهزة استشعار الحركة في الجهاز لتحديد الوضع الجغرافي المكاني للجهاز. لا يتوفّر هذا الوضع على أجهزة النظارات الذكية.
  • GeospatialMode.INERTIAL: تم تفعيل Geospatial API في وضع توفير الطاقة. تستخدم Geospatial API نظام GPS وأجهزة استشعار الحركة في الجهاز فقط لتحديد الوضع الجغرافي المكاني للجهاز. لا يتوفّر هذا الوضع إلا على أجهزة النظارات الذكية.
  • GeospatialMode.DISABLED: تكون Geospatial API غير مفعَّلة. وعند الانتقال من وضع آخر إلى هذا الوضع، تحرّر Geospatial API جميع الموارد المكتسَبة وتتوقف عن التتبُّع.

لا تتوافق بعض الأجهزة مع جميع أوضاع Geospatial. يمكنك الاطّلاع على GeospatialMode لمزيد من المعلومات. استخدِم XrDevice.isGeospatialSupported لمعرفة ما إذا كان GeospatialMode معيّن متاحًا.

توضّح عيّنة التعليمات البرمجية التالية كيفية ضبط GeospatialMode باستخدام Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}

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

يجب أن تعرض التطبيقات التي تستخدم Geospatial API مع ARCore for Jetpack XR إشعارًا للمستخدم يطلب منه الموافقة على استخدام البيانات من جهازه والسماح بذلك. لمزيد من المعلومات، يمكنك الاطّلاع على متطلبات خصوصية المستخدم.

استخدام عنصر Geospatial

بعد ضبط الجلسة، يمكنك الحصول على عنصر Geospatial باستخدام Geospatial.getInstance. استخدِم الكائن Geospatial فقط عندما تكون حالته GeospatialTrackingState.RUNNING.

توضّح عيّنات التعليمات البرمجية التالية كيفية مراقبة الحالة الجغرافية المكانية باستخدام Geospatial.state.

Compose XR

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}

SceneCore

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}

فهم قيم الدقة

عند تفعيل Geospatial API، توفّر هذه الواجهة ثلاث قيم للدقة: الدقة الأفقية والعمودية ودقة الاتجاه. يتم تعديل قيم الدقة هذه بمرور الوقت ويمكن جعلها أكثر دقة مع الحصول على المزيد من البيانات. تشير القيم الأكبر إلى دقة أقل، ويتم تحديدها على أنّها نصف قطر مستوى ثقة يبلغ %68. بعبارة أخرى، هناك احتمال بنسبة% 68 أن تكون القيمة الحقيقية ضمن النطاق المحدّد للقيمة المقدَّرة.

استخدِم Geospatial.State.horizontalAccuracy وverticalAccuracy وorientationYawAccuracy للحصول على قيم الدقة الحالية.

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

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

عند إعداد Geospatial API بشكل صحيح في تطبيقك، يمكن لتطبيقك إجراء ما يلي: