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

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

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

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

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

تفعيل ARCore API

قبل استخدام ميزة "تثبيتات السحابة الإلكترونية" في تطبيقك، عليك أولاً تفعيل واجهة برمجة التطبيقات 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.

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

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

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

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

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

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

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

يمكنك بدء عمليات حلّ لعدة منصات في السحابة الإلكترونية بالتسلسل. يمكن أن تتوفّر ما يصل إلى 40 عملية متزامنة من عمليات "تثبيت العناصر في السحابة الإلكترونية" في الوقت نفسه.

إلغاء عملية أو إزالة 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 API الحصص التالية لمعدل نقل بيانات الطلبات:

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

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

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

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

  • أبقِ الكاميرا مدرَّبة على مركز الاهتمام وحرِّك الجهاز حول مركز الاهتمام لرسم خريطة للبيئة من زوايا مختلفة مع الحفاظ على المسافة المادية نفسها تقريبًا. سيساعد ذلك في التقاط المزيد من البيانات المرئية وتسهيل عملية التحليل.

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

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

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

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