تعرَّف على كيفية استخدام Cloud Anchors في تطبيقاتك الخاصة.
المتطلبات الأساسية
قبل المتابعة، تأكد من فهم مفاهيم الواقع المعزّز الأساسية وكيفية ضبط جلسة ARCore.
إذا كنت مستخدمًا جديدًا لتطبيق Cloud Anchors:
- احرص على فهم آلية عمل الإعلانات الثابتة والإعلانات الثابتة في السحابة الإلكترونية.
- اقرأ quickstart لـ Cloud Anchors لمعرفة تعليمات الإعداد والإعداد والتثبيت.
تفعيل ARCore API
قبل استخدام Cloud Anchors في تطبيقك، عليك أولاً تفعيل ARCore API في تطبيقك.
تفعيل إمكانات Cloud Anchor في إعداد الجلسة
بعد تفعيل وظيفة Cloud Anchors في تطبيقك، عليك تفعيل إمكانات Cloud Anchors في إعدادات جلسة الواقع المعزّز في تطبيقك لكي يكون بإمكان التطبيق التواصل مع واجهة برمجة التطبيقات ARCore API:
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)
استضافة تثبيت على السحابة الإلكترونية
تبدأ الاستضافة بمكالمة إلى الرقم hostCloudAnchorAsync()
. سيحمّل تطبيق ARCore البيانات المرئية ووضعيات الجهاز ووضع الإرساء إلى واجهة برمجة تطبيقات ARCore. بعد ذلك، تعالج واجهة برمجة التطبيقات هذه المعلومات لإنشاء خريطة ميزات ثلاثية الأبعاد، ما يؤدي في النهاية إلى عرض معرّف Cloud Anchor فريد للارتساء إلى الجهاز.
يمكنك أيضًا تمديد عمر إعلان ثابت مستضاف على ARCore Cloud Anchor Management API.
يجب أن يتّبع تطبيقك الخطوات التالية لإكمال استضافة Cloud Anchor:
- يمكنك الاتصال بالرقم
hostCloudAnchorAsync()
. - انتظِر حتى يتم معاودة الاتصال أو تحقَّق باستمرار من الحالة المستقبلية إلى أن تكتمل العملية.
- تحقَّق من حالة النتيجة لتحديد ما إذا نجحت العملية، أو لتفسير رمز الخطأ في حال تعذّر إتمامها.
- يمكنك مشاركة معرّف Cloud Anchor للنتيجة مع برامج أخرى، واستخدامها لحل مشكلة Cloud Anchor مع
resolveCloudAnchorAsync()
.
التحقق من جودة تخطيط نقاط الخصائص
يشير الرمز Session.FeatureMapQuality
إلى جودة نقاط الميزات التي رصدها ARCore خلال الثواني القليلة السابقة من وضع الكاميرا المحدّد. عادةً ما يتم التعامل بشكل أكثر دقة مع البرامج المثبّتة على السحابة الإلكترونية المستضافة من خلال ميزات عالية الجودة. استخدِم Session.estimateFeatureMapQualityForHosting()
للحصول على تقدير لجودة خريطة الميزات لوضعية معيّنة في الكاميرا.
القيمة | الوصف |
---|---|
INSUFFICIENT |
جودة نقاط الخصائص التي تم تحديدها من الوضعية في الثواني القليلة السابقة منخفضة. تشير هذه الحالة إلى أنّه من المحتمل أن يواجه ARCore صعوبة أكبر في حلّ مشكلة مراسي Cloud. يمكنك تشجيع المستخدم على تحريك الجهاز بحيث يمكن عرض الموضع المطلوب من Cloud Anchor الذي يريد استضافته من زوايا مختلفة. |
SUFFICIENT |
من المحتمل أن تكون جودة نقاط الخصائص التي تم تحديدها من الوضعية في الثواني القليلة السابقة كافية لحل مشكلة Cloud Anchor بنجاح، على الرغم من احتمال انخفاض دقة الوضع الذي تم حله. يمكنك تشجيع المستخدم على تحريك الجهاز بحيث يمكن عرض الموضع المطلوب من Cloud Anchor الذي يريد استضافته من زوايا مختلفة. |
GOOD |
من المرجح أن تكون جودة نقاط الخصائص التي تم تحديدها من الوضعية في الثواني القليلة السابقة كافية لحل مشكلة Cloud Anchor بنجاح. |
حل موضع ثابت تمت استضافته سابقًا
يمكنك الاتصال بـ resolveCloudAnchorAsync()
لحل مشكلة Cloud Anchor مستضافة. تقارن واجهة برمجة تطبيقات ARCore دوريًا بين الميزات المرئية من المشهد وخريطة ميزات ثلاثية الأبعاد للارتساء لتحديد موضع المستخدم واتجاهه بالنسبة إلى الارتساء. وعندما يعثر على مطابقة، تعرض واجهة برمجة التطبيقات وضع Cloud Anchor المستضاف.
يمكنك بدء عمليات الحل لعدّة "ثبات Cloud" على التوالي. يمكن أن يتوفر ما يصل إلى 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. وقد يحدث ذلك نتيجة لعدة أسباب. قد يكون الجهاز في وضع الطيران أو قد لا يتوفر اتصال سليم بالإنترنت. ربما انتهت مهلة الطلب المُرسَل إلى الخادم بدون استجابة. قد يكون هناك مشكلة في الاتصال بالشبكة أو عدم توفُّر نظام أسماء النطاقات أو مشاكل في الجدار الناري أو أي مشكلة أخرى قد تؤثر في قدرة الجهاز على الاتصال بواجهة برمجة تطبيقات ARCore. |
ERROR_INTERNAL |
انتهت مهمة استضافة أو حل مشكلة الارتساء هذه بخطأ داخلي. يجب ألا يحاول التطبيق إصلاح هذا الخطأ. |
ERROR_NOT_AUTHORIZED |
التفويض المقدَّم من التطبيق غير صالح. يُرجى الاطّلاع على تحديد المشاكل وحلّها في تفويض ARCore API. |
ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
تعذّر حل Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحلّ الارتساء هو أحدث من الإصدار المستخدَم لاستضافة الإعلان وغير متوافق معه. |
ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
تعذّر حل Cloud Anchor لأنّ إصدار حزمة تطوير البرامج (SDK) المستخدَم لحل علامة الارتساء أقدم من الإصدار المستخدَم لاستضافتها، وغير متوافق معه. |
ERROR_RESOURCE_EXHAUSTED |
لقد استنفد التطبيق حصّة الطلب المخصّصة لمشروع Google Cloud المحدّد. يجب طلب حصة إضافية من ARCore API لمشروعك من Google Developers Console. |
SUCCESS |
تمّ بنجاح إكمال مهمة استضافة أو حل لهذا الإعلان الارتساءي. |
حصص واجهة برمجة التطبيقات لطلبات المضيف وحلّ المشاكل
تتضمن واجهة برمجة تطبيقات ARCore الحصص التالية لمعدل نقل البيانات للطلب:
نوع الحصة | الحد الأقصى | المدة | ينطبق على |
---|---|---|---|
عدد مرات الارتساء | غير محدودة | لا ينطبق | المشروع |
طلبات إعلانات المضيف الثابتة | 30 | دقيقة | عنوان IP والمشروع |
طلبات resolve الارتساء | 300 | دقيقة | عنوان IP والمشروع |
أفضل الممارسات لترك انطباع جيد لدى المستخدم
يُرجى توجيه المستخدمين إلى تنفيذ ما يلي لضمان تقديم تجربة جيدة للمستخدمين في تطبيقك:
- انتظِر بضع ثوانٍ بعد بدء الجلسة قبل محاولة استضافة علامة ارتساء (عن طريق وضع كائن وما إلى ذلك). يمنح ذلك التتبّع بعض الوقت للاستقرار.
- عند تحديد موقع لاستضافة الإعلان الثابت، حاول العثور على منطقة تضم ميزات مرئية يمكن تمييزها بسهولة عن بعضها البعض. للحصول على أفضل النتائج، تجنَّب الأسطح أو الأسطح العاكسة التي تفتقر إلى الميزات المرئية، مثل الجدران البيضاء الفارغة.
حافِظ على تركيز الكاميرا على مركز الاهتمام وحرِّك الجهاز حول مركز الاهتمام لرسم خريطة للبيئة من زوايا مختلفة، مع الحفاظ على المسافة المادية نفسها تقريبًا كما ستفعل. سيساعد ذلك على التقاط المزيد من البيانات المرئية وجعل التحليل أكثر فعالية.
تأكَّد من توفّر إضاءة كافية في بيئة الحياة الواقعية أثناء استضافة Cloud Anchors وحلّ مشاكلها.
سياسة الإيقاف
- تخضع التطبيقات التي تم إنشاؤها باستخدام ARCore SDK 1.12.0 أو إصدار أحدث إلى سياسة إيقاف واجهة برمجة التطبيقات Cloud Anchor API.
- يتعذّر على التطبيقات التي تم إنشاؤها باستخدام حزمة SDK 1.11.0 أو إصدار أقدم من ARCore استضافة أو حلها في Cloud Anchors، وذلك بسبب استخدام SDK لـ ARCore API قديم ومتوقّف.
الخطوات التالية
- يمكنك إنشاء تطبيق Cloud Anchors باستخدام الدرس التطبيقي حول ترميز ARCore Cloud Anchors مع ميزة Cloud Anchors الدائمة.
- يمكنك التعرّف على كيفية استضافة البرامج الثابتة في Cloud وحلها من خلال نموذجَين للتطبيق في البدء السريع لـ Cloud Anchors.
- يمكنك إدارة Cloud Anchors خارج تطبيق ARCore باستخدام واجهة برمجة تطبيقات Cloud anchors Management.
- يمكنك مراجعة المستندات المرجعية لنظام التشغيل Android للتعرّف على مزيد من الطرق لاستخدام ARCore في تطبيقك.