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

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

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

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

إذا كنت مستخدمًا جديدًا لتطبيق 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:

  1. يُرجى الاتصال على hostCloudAnchorAsync().
  2. انتظِر تلقّي مكالمة من الفريق أو تحقّق باستمرار من حالة "في المستقبل" إلى أن تكتمل العملية.
  3. تحقّق من حالة النتيجة لتحديد ما إذا نجحت العملية أو تفسير رمز الخطأ في حال تعذّر إكمالها.
  4. شارِك مع العملاء الآخرين معرّف 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 قديمة تم إيقافها نهائيًا.

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