تم إيقاف نقطة النهاية القديمة لسحابة ARCore Cloud Anchor API نهائيًا ولن تعود متاحة بعد 31 آب (أغسطس) 2023. إذا كان تطبيقك يستخدم واجهة برمجة التطبيقات هذه، عليك تحديثها لاستخدام نقطة نهاية السحابة الإلكترونية ARCore API الجديدة في أقرب وقت ممكن.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

تأكَّد من فهم مفاهيم الواقع المعزّز الأساسية وكيفية ضبط جلسة ARCore قبل المتابعة.

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

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

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

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

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

استضافة "مرساة السحابة الإلكترونية"

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

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

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

يُرجى الاتصال على ARAnchorManager.HostCloudAnchorAsync().
ابدأ دالة معالجة متزامنة للانتظار إلى أن يقدّم الوعد نتيجة. اطّلِع على الوظائف المتكرّرة في Unity للحصول على معلومات إضافية.
تحقَّق من حالة النتيجة لتحديد ما إذا نجحت العملية أو فكِّر رمز الخطأ في حال تعذّر إكمالها.
شارِك مع العملاء الآخرين معرّف 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 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 Extensions المستخدَمة لحلّ Cloud Anchor أحدث من الإصدار المستخدَم لاستضافته وغير متوافقة معه.
`ErrorResolvingPackageTooOld`	تعذّر حلّ Cloud Anchor لأنّ حزمة ARCore Extensions المستخدَمة لحلّ Cloud Anchor أقدم من الإصدار المستخدَم لاستضافته وغير متوافقة معه.
`ErrorResourceExhausted`	استنفد التطبيق حصة الطلبات المخصّصة لمشروع Google Cloud المحدّد. يجب طلب حصة إضافية لواجهة برمجة التطبيقات ARCore لمشروعك من Google Developers Console.
`Success`	اكتملت مهمة استضافة أو حلّ لهذه النقطة الأساسية بنجاح.

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

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

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

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

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

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

ملاحظة: إنّ التنقّل حول نقطة الاهتمام ليس هو نفسه الثبات في مكان واحد والدوران، كما قد يفعل شخص ما عند التقاط لقطة بانورامية. يجب أن يتحرك المستخدمون جسديًا في جميع أنحاء البيئة.
تأكَّد من توفُّر إضاءة كافية في البيئة الواقعية أثناء استضافة "محطات الربط في السحابة الإلكترونية" وتحديد مواقعها.

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

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

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

اطّلِع على مستندات مرجعية لـ "إضافات ARCore" لإطار عمل AR Foundation للتعرّف على المزيد من الطرق لاستخدام ARCore في تطبيقك.