دليل مطوِّري Cloud Anchors لنظام التشغيل Unity (AR Foundation)

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

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

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

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

تفعيل ARCore API

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

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

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

استضافة Cloud Anchor

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

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

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

  1. يمكنك الاتصال بالرقم ARAnchorManager.HostCloudAnchorAsync().
  2. ابدأ الكوروتين والانتظار حتى يعطيك الوعد نتيجة. راجِع Coroutines في Unity للحصول على معلومات إضافية.
  3. التحقّق من حالة النتائج لتحديد ما إذا نجحت العملية أو تفسير رمز الخطأ في حال عدم نجاحها
  4. شارِك معرّف Cloud Anchor نتيجة البحث مع برامج أخرى، واستخدِمه لحل Cloud Anchor النتيجة عبر ARAnchorManagerExtensions.ResolveCloudAnchorAsync()

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

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

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

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

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

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

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

يتم استدعاء ARCloudAnchor.OnDestroy() تلقائيًا عند إزالة المكوِّن ARCloudAnchor من كائن اللعبة الذي يحتوي عليه. سيؤدي هذا إلى فصل كائن Cloud Anchor الأساسي وإطلاقه.

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

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

القيمة الوصف
ErrorResolvingCloudIdNotFound تعذّر حلّ المشكلة بسبب عدم تمكّن واجهة برمجة تطبيقات ARCore من العثور على رقم تعريف Cloud Anchor المقدَّم.
ErrorHostingDatasetProcessingFailed تعذّرت الاستضافة بسبب عدم تمكّن الخادم من معالجة مجموعة البيانات الخاصة بعلامة الارتساء المحدّدة بنجاح. يُرجى إعادة المحاولة بعد أن يجمع الجهاز المزيد من البيانات من البيئة.
ErrorHostingServiceUnavailable تعذّر الوصول إلى ARCore API. وقد يحدث ذلك نتيجة لعدة أسباب. قد يكون الجهاز في "وضع الطيران" أو قد لا يتوفّر به اتصال إنترنت صالح. قد تكون المهلة المحددة للطلب المرسَل إلى الخادم قد انتهت بدون استجابة. قد يكون هناك اتصال سيئ بالشبكة أو عدم توفُّر نظام أسماء النطاقات أو مشاكل في جدار الحماية أو أي مشاكل أخرى قد تؤثر في قدرة الجهاز على الاتصال بواجهة برمجة تطبيقات ARCore.
ErrorInternal انتهت مهمة الاستضافة أو الحل لهذا الإعلان الثابت بسبب خطأ داخلي. ويجب ألا يحاول التطبيق استعادة رسالة الخطأ هذه.
ErrorNotAuthorized لا يمكن للتطبيق الاتصال بواجهة برمجة تطبيقات ARCore بسبب التفويض غير الصالح. تحقق من إعدادات المشروع > XR > إضافات ARCore للحصول على استراتيجية تفويض صالحة.
ErrorResolvingPackageTooNew تعذّر حلّ Cloud Anchor لأنّ حزمة إضافات ARCore المُستخدَمة لحل Cloud Anchor أحدث من الإصدار المستخدَم لاستضافتها وغير متوافقة معه.
ErrorResolvingPackageTooOld تعذّر حلّ Cloud Anchor لأنّ حزمة إضافات ARCore المُستخدَمة لحل Cloud Anchor قديمة من الإصدار المستخدَم لاستضافتها وغير متوافقة معه.
ErrorResourceExhausted استنفد التطبيق حصة الطلبات المخصّصة لمشروع Google Cloud المحدّد. يجب طلب حصة إضافية من واجهة برمجة تطبيقات ARCore لمشروعك من Google Developers Console.
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 قديمة ومتوقّفة نهائيًا.

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