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

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

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

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

إذا كنت مبتدئًا في استخدام ميزة "محطات الربط في السحابة الإلكترونية"، احرص على فهم آلية عمل محطات الربط ومحطات الربط في السحابة الإلكترونية.

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

قبل استخدام ميزة "تثبيتات السحابة الإلكترونية" في تطبيقك، عليك أولاً تفعيل واجهة برمجة التطبيقات ARCore API في تطبيقك.

تفعيل إمكانات Cloud Anchor في إعدادات الجلسة

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

استضافة Cloud Anchor

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

يمكنك أيضًا إطالة مدة عمل العنصر الأساسي المستضاف باستخدام ARCore Cloud Anchor Management API.

يجب أن يتّبع تطبيقك الخطوات التالية لإكمال استضافة "نقطة ارتساء السحابة الإلكترونية":

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

التحقّق من جودة ربط نقاط العناصر

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

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

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

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

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

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

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

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

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

القيمة الوصف
ErrorResolvingCloudIdNotFound تعذّر حلّ المشكلة لأنّ واجهة برمجة التطبيقات ARCore API لم تتمكّن من العثور على معرّف Cloud Anchor المقدَّم.
ErrorHostingDatasetProcessingFailed تعذّرت الاستضافة بسبب عدم تمكّن الخادم من معالجة مجموعة البيانات الخاصة بعلامة الارتساء المحدّدة بنجاح. يُرجى إعادة المحاولة بعد أن يجمع الجهاز المزيد من البيانات من البيئة.
ErrorHostingServiceUnavailable تعذّر الوصول إلى واجهة برمجة التطبيقات ARCore API. وقد يحدث ذلك نتيجة لعدة أسباب. قد يكون الجهاز في وضع الطيران أو قد لا يكون متصلاً بالإنترنت. قد تكون مهلة الطلب المرسَل إلى الخادم قد انتهت بدون تلقّي أي استجابة. قد يكون هناك اتصال ضعيف بالشبكة أو عدم توفّر نظام أسماء النطاقات (DNS) أو مشاكل في جدار الحماية أو أي شيء آخر قد يؤثر في قدرة الجهاز على الاتصال بواجهة برمجة التطبيقات ARCore API.
ErrorInternal اكتملت مهمة استضافة أو حلّ لهذه النقطة الأساسية بظهور خطأ داخلي. من المفترض ألا يحاول التطبيق معالجة هذا الخطأ.
ErrorNotAuthorized لا يمكن للتطبيق التواصل مع واجهة برمجة التطبيقات ARCore API بسبب تفويض غير صالح. انتقِل إلى إعدادات المشروع > XR > إضافات ARCore للاطّلاع على استراتيجية تفويض صالحة.
ErrorResolvingPackageTooNew تعذّر حلّ Cloud Anchor لأنّ حزمة إضافات ARCore المُستخدَمة لحل Cloud Anchor أحدث من الإصدار المستخدَم لاستضافتها وغير متوافقة معه.
ErrorResolvingPackageTooOld تعذّر حلّ Cloud Anchor لأنّ حزمة ARCore Extensions المستخدَمة لحلّ Cloud Anchor أقدم من الإصدار المستخدَم لاستضافته وغير متوافقة معه.
ErrorResourceExhausted استنفد التطبيق حصة الطلبات المخصّصة لمشروع Google Cloud المحدّد. يجب طلب حصة إضافية لواجهة برمجة التطبيقات ARCore لمشروعك من Google Developers Console.
Success اكتملت مهمة الاستضافة أو الحلول الخاصة بهذا الارتساء بنجاح.

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

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

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

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

يُرجى توجيه المستخدمين إلى تنفيذ ما يلي لضمان تقديم تجربة جيدة لهم في تطبيقك:

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

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

  • تأكَّد من توفُّر إضاءة كافية في البيئة الواقعية أثناء استضافة "محطات الربط في السحابة الإلكترونية" وتحديد مواقعها.

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

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

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