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

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

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

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

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

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

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