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

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

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

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

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

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

إذا كنت مستخدمًا جديدًا لتطبيق Cloud Anchors:

احرص على فهم آلية عمل نقاط الربط ونقاط الربط في السحابة الإلكترونية.
راجِع التشغيل السريع في Cloud Anchors للاطّلاع على متطلبات النظام وتعليمات الإعداد والتثبيت.

تفعيل ARCore API

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

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

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

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

استضافة Cloud Anchor

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

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

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

يُرجى الاتصال على hostCloudAnchorAsync().
انتظِر تلقّي مكالمة من الفريق أو تحقّق باستمرار من حالة "في المستقبل" إلى أن تكتمل العملية.
تحقّق من حالة النتيجة لتحديد ما إذا نجحت العملية أو تفسير رمز الخطأ في حال تعذّر إكمالها.
شارِك مع العملاء الآخرين معرّف Cloud Anchor الناتج، واستخدِمه لحلّ Cloud Anchor باستخدام resolveCloudAnchorAsync().

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

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

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

حلّ نقطة إرساء مستضافة سابقًا

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

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

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

يمكنك الاتصال بالرقم cancel() لإلغاء عملية في Cloud Anchor معلَّقة. اتصل برقم detach() لإزالة Cloud Anchor تم حلّه من التطبيق.

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

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

القيمة	الوصف
`ERROR_CLOUD_ID_NOT_FOUND`	تعذّر حلّ المشكلة بسبب عدم تمكّن واجهة برمجة تطبيقات ARCore من العثور على رقم تعريف Cloud Anchor المقدَّم.
`ERROR_HOSTING_DATASET_PROCESSING_FAILED`	تعذّر الاستضافة لأنّ الخادم لم يتمكّن من معالجة مجموعة البيانات للإشارة المحدّدة بنجاح. يُرجى إعادة المحاولة بعد أن يجمع الجهاز المزيد من البيانات من البيئة.
`ERROR_HOSTING_SERVICE_UNAVAILABLE`	تعذّر الوصول إلى واجهة برمجة التطبيقات ARCore API. وقد يحدث ذلك نتيجة لعدة أسباب. قد يكون الجهاز في وضع الطيران أو قد لا يكون متصلاً بالإنترنت. من المحتمل أنّه انتهت مهلة الطلب المرسَل إلى الخادم بدون تلقّي أي استجابة. قد يكون هناك اتصال ضعيف بالشبكة أو عدم توفّر نظام أسماء النطاقات (DNS) أو مشاكل في جدار الحماية أو أي شيء آخر قد يؤثر في قدرة الجهاز على الاتصال بواجهة برمجة التطبيقات ARCore API.
`ERROR_INTERNAL`	انتهت مهمة الاستضافة أو الحل لهذا الإعلان الثابت بسبب خطأ داخلي. من المفترض ألا يحاول التطبيق معالجة هذا الخطأ.
`ERROR_NOT_AUTHORIZED`	التفويض الذي يقدّمه التطبيق غير صالح. يُرجى الاطّلاع على تحديد المشاكل وحلّها في تفويض واجهة برمجة تطبيقات ARCore.
`ERROR_RESOLVING_SDK_VERSION_TOO_NEW`	تعذّر حلّ Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحل الارتساء أحدث من الإصدار المستخدَم لاستضافتها وغير متوافق معه.
`ERROR_RESOLVING_SDK_VERSION_TOO_OLD`	تعذّر حلّ Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحل الارتساء أقدم من الإصدار المستخدَم لاستضافتها وغير متوافق معه.
`ERROR_RESOURCE_EXHAUSTED`	استنفد التطبيق حصة الطلبات المخصّصة لمشروع Google Cloud المحدّد. ويجب طلب حصة إضافية من واجهة برمجة تطبيقات ARCore لمشروعك من Google Developers Console.
`SUCCESS`	اكتملت مهمة الاستضافة أو الحلول الخاصة بهذا الارتساء بنجاح.

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

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

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

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

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

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

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

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

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

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

أنشِئ تطبيق Cloud Anchors باستخدام الدرس التطبيقي حول ترميز Cloud Anchors الدائم في ARCore Cloud Anchors.
اطّلِع على كيفية استضافة عناصر Cloud Anchors وحلّها من خلال نموذجَين للتطبيقات في الدليل السريع لاستخدام عناصر Cloud Anchors.
يمكنك إدارة Cloud Anchors خارج تطبيق ARCore باستخدام Cloud Anchors Management API.
يمكنك الاطّلاع على المستندات المرجعية لنظام التشغيل Android لمزيد من الطرق لاستخدام ARCore في تطبيقك.