دليل المطوِّر في Cloud Anchors لنظام التشغيل Android NDK (C)

تعرَّف على كيفية استخدام Cloud Anchors في تطبيقاتك.

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

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

إذا كنت مستخدمًا مبتدئًا لـ Cloud Anchors، احرِص على فهم آلية عمل الارتساء وCloud Anchors.

تفعيل ARCore API

قبل استخدام Cloud Anchors في تطبيقك، عليك أولاً تفعيل ARCore API في تطبيقك.

تفعيل إمكانات Cloud Anchor في ضبط الجلسة

بعد تفعيل وظائف Cloud Anchors في تطبيقك، يمكنك تفعيل إمكانات Cloud Anchors في ضبط جلسة الواقع المعزّز على تطبيقك حتى يتمكّن من التواصل مع ARCore API:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

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

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

استضافة Cloud Anchor

تبدأ الاستضافة بمكالمة إلى ArSession_hostCloudAnchorAsync(). سيُحمِّل ARCore البيانات المرئية ووضعات الجهاز ووضع الإرساء على واجهة برمجة تطبيقات ARCore. بعد ذلك، تعالج واجهة برمجة التطبيقات هذه المعلومات لإنشاء خريطة ميزات ثلاثية الأبعاد، ما يؤدي في النهاية إلى عرض معرّف Cloud Anchor فريد للارتساء إلى الجهاز.

ويمكنك أيضًا إطالة عمر إعلان ثابت مُستضاف باستخدام واجهة برمجة التطبيقات ARCore Cloud Anchor Management API.

يجب أن يتّبع تطبيقك هذه الخطوات لإكمال استضافة Cloud Anchor:

  1. يمكنك الاتصال بالرقم ArSession_hostCloudAnchorAsync().
  2. انتظر معاودة الاتصال، أو تحقَّق باستمرار من حالة "المستقبل" حتى ينتهي.
  3. التحقّق من حالة النتائج لتحديد ما إذا نجحت العملية أو تفسير رمز الخطأ في حال عدم نجاحها
  4. شارِك معرّف Cloud Anchor نتيجة البحث مع برامج أخرى، واستخدِمه لحل Cloud Anchor النتيجة عبر ArSession_resolveCloudAnchorAsync()

التحقق من جودة تعيين نقاط الخصائص

يشير ArFeatureMapQuality إلى جودة نقاط الميزات التي يراها ARCore في الثواني القليلة السابقة من وضع كاميرا معيّن. بشكل عام، يتم التعامل مع Cloud Anchors (ارتساء السحابة الإلكترونية) المستضافة باستخدام ميزات ذات جودة أعلى، بشكل أكثر دقة. استخدِم ArSession_estimateFeatureMapQualityForHosting() للحصول على تقدير لجودة خريطة الميزات لوضع كاميرا معيّن.

القيمة الوصف
INSUFFICIENT جودة نقاط الميزات التي تم تحديدها من الوضع خلال الثواني القليلة السابقة منخفضة. تشير هذه الحالة إلى أنّ ARCore سيواجه على الأرجح صعوبة أكبر في حلّ Cloud Anchor. شجِّع المستخدم على تحريك الجهاز بحيث يمكن عرض الموضع المطلوب من Cloud Anchor الذي يريد استضافته من زوايا مختلفة.
SUFFICIENT من المرجّح أن تكون جودة نقاط الميزات التي تم تحديدها من خلال الوضعية خلال الثواني القليلة السابقة كافية لكي يتمكّن ARCore من حلّ مشكلة Cloud Anchor بنجاح، إلا أنّ دقة الوضع الذي تم تحديده ستنخفض على الأرجح. شجِّع المستخدم على تحريك الجهاز بحيث يمكن عرض الموضع المطلوب من Cloud Anchor الذي يريد استضافته من زوايا مختلفة.
GOOD من المرجّح أن تكون جودة نقاط الميزات التي تم تحديدها من خلال الوضع خلال الثواني القليلة السابقة كافية لكي يتمكّن ARCore من حلّ مشكلة Cloud Anchor بنجاح بدرجة عالية من الدقة.

التعامل بشكل نهائي مع إعلان ارتساء تمت استضافته في السابق

يمكنك الاتصال بالرقم ArSession_resolveCloudAnchorAsync() لحلّ مشكلة Cloud Anchor مستضاف. تقارن ARCore API بشكل دوري الميزات المرئية من المشهد بخريطة الميزات الثلاثية الأبعاد الخاصة بالارتساء لتحديد موضع المستخدم واتجاهه بالنسبة إلى علامة الارتساء. وعند العثور على تطابق، تعرض واجهة برمجة التطبيقات وضع Cloud Anchor المستضافة.

يمكنك بدء عمليات حلّ لعدة منصات في السحابة الإلكترونية بالتسلسل. يمكن أن يتوفر ما يصل إلى 40 عملية مزامنة في Cloud Anchor في آنٍ واحد.

إلغاء عملية أو إزالة Cloud Anchor

يمكنك الاتصال بالرقم ArFuture_cancel() لإلغاء عملية في Cloud Anchor معلَّقة. يمكنك الاتصال بالرقم ArAnchor_detach() لإيقاف التتبُّع وحذف قاعدة Cloud Anchor التي سبق أن تم حلها. يجب إصدار الإشارات إلى الإعلان الثابت بشكل منفصل من خلال الاتصال بالرقم ArAnchor_release().

التحقّق من حالة نتيجة عملية Cloud Anchor

استخدِم ArCloudAnchorState للاطّلاع على حالة نتيجة عملية الاستضافة أو الحل، بما في ذلك الأخطاء.

القيمة الوصف
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND تعذّر حلّ المشكلة بسبب عدم تمكّن واجهة برمجة تطبيقات ARCore من العثور على رقم تعريف Cloud Anchor المقدَّم.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED تعذّرت الاستضافة بسبب عدم تمكّن الخادم من معالجة مجموعة البيانات الخاصة بعلامة الارتساء المحدّدة بنجاح. يُرجى إعادة المحاولة بعد أن يجمع الجهاز المزيد من البيانات من البيئة.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE تعذّر الوصول إلى ARCore API. وقد يحدث ذلك نتيجة لعدة أسباب. قد يكون الجهاز في "وضع الطيران" أو قد لا يتوفّر به اتصال إنترنت صالح. قد تكون المهلة المحددة للطلب المرسَل إلى الخادم قد انتهت بدون استجابة. قد يكون هناك اتصال سيئ بالشبكة أو عدم توفُّر نظام أسماء النطاقات أو مشاكل في جدار الحماية أو أي مشاكل أخرى قد تؤثر في قدرة الجهاز على الاتصال بواجهة برمجة تطبيقات ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL انتهت مهمة الاستضافة أو الحل لهذا الإعلان الثابت بسبب خطأ داخلي. ويجب ألا يحاول التطبيق استعادة رسالة الخطأ هذه.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED يُرجى الاطّلاع على تحديد المشاكل وحلّها في تفويض واجهة برمجة تطبيقات ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW تعذّر حلّ Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحل الارتساء أحدث من الإصدار المستخدَم لاستضافتها وغير متوافق معه.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD تعذّر حلّ Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحل الارتساء أقدم من الإصدار المستخدَم لاستضافتها وغير متوافق معه.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED استنفد التطبيق حصة الطلبات المخصّصة لمشروع Google Cloud المحدّد. يجب طلب حصة إضافية من واجهة برمجة تطبيقات ARCore لمشروعك من Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS اكتملت مهمة الاستضافة أو الحلول الخاصة بهذا الارتساء بنجاح.

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

توفّر واجهة برمجة التطبيقات ARCore الحصص التالية لمعدل نقل البيانات للطلب:

نوع الحصة الحد الأقصى المدة ينطبق على
عدد علامات الارتساء غير محدودة لا ينطبق المشروع
طلبات مضيف ثابتة 30 دقيقة عنوان IP والمشروع
طلبات الحل للارتساء 300 دقيقة عنوان IP والمشروع

أفضل الممارسات لتقديم تجربة جيدة للمستخدم

قدِّم تعليمات للمستخدمين باتّباع الخطوات التالية لضمان تقديم تجربة جيدة للمستخدمين على تطبيقك:

  • يُرجى الانتظار بضع ثوانٍ بعد بدء الجلسة قبل محاولة استضافة إعلان ثابت. (عن طريق وضع كائن ما، وما إلى ذلك). وهذا يمنح التتبع بعض الوقت للاستقرار.
  • عند اختيار موقع لاستضافة الإرساء، حاول العثور على منطقة ذات ميزات مرئية يمكن تمييزها بسهولة عن بعضها البعض. للحصول على أفضل النتائج، تجنَّب الأسطح العاكسة أو الأسطح التي تفتقر إلى الميزات المرئية، مثل الجدران البيضاء الفارغة.

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

  • تأكَّد من توفّر إضاءة كافية في بيئة حقيقية أثناء استضافة Cloud Anchors وحلّ مشاكله.

سياسة الإيقاف النهائي

  • يتم تطبيق سياسة الإيقاف النهائي لواجهة Cloud Anchor API على التطبيقات التي تم إنشاؤها باستخدام ARCore SDK 1.12.0 أو إصدار أحدث.
  • يتعذّر على التطبيقات التي تم إنشاؤها باستخدام الإصدار 1.11.0 من حزمة تطوير البرامج (SDK) من ARCore أو إصدار أقدم من استضافة Cloud Anchors أو حلها، وذلك بسبب استخدام حزمة SDK لواجهة برمجة تطبيقات ARCore قديمة ومتوقّفة نهائيًا.

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