Android को टारगेट करने वाले ARCore एक्सटेंशन के लिए क्लाउड ऐंकर डेवलपर गाइड

अपने ऐप्लिकेशन में Cloud ऐंकर इस्तेमाल करने का तरीका जानें.

ज़रूरी शर्तें

पक्का करें कि आपको फ़ंड के बुनियादी सिद्धांत पता हैं. साथ ही, आगे बढ़ने से पहले, ARCore सेशन को कॉन्फ़िगर करने का तरीका जानें.

अगर आपके लिए क्लाउड ऐंकर नया है, तो पक्का करें कि आपने ऐंकर और क्लाउड ऐंकर के काम करने का तरीका समझ लिया है.

ARCore एपीआई को चालू करें

अपने ऐप्लिकेशन में Cloud ऐंकर का इस्तेमाल करने से पहले, आपको नए या मौजूदा Google Cloud Platform प्रोजेक्ट में ARCore API की सुविधा चालू करनी होगी. यह सेवा क्लाउड ऐंकर को होस्ट करने, सेव करने, और ठीक करने के लिए ज़िम्मेदार है.

अपने ऐप्लिकेशन को ARCore API पर कॉल करने की अनुमति दें

आपको क्लाउड ऐंकर को होस्ट करने और उनका समाधान करने के लिए, अपने ऐप्लिकेशन को ARCore एपीआई को कॉल करने की अनुमति देनी होगी. ऐसे ऐप्लिकेशन जो 1 से ज़्यादा TTL (टीटीएल) वाले क्लाउड ऐंकर को होस्ट और रिज़ॉल्व करते हैं उन्हें बिना कुंजी के इस्तेमाल करने की अनुमति का इस्तेमाल करना होगा.

अपने ऐप्लिकेशन में क्लाउड ऐंकर की सुविधा चालू करना

अपने ऐप्लिकेशन को ARCore API पर कॉल करने की अनुमति देने के बाद, आपको अपने ऐप्लिकेशन में Cloud ऐंकर की सुविधा चालू करनी होगी.

1. बदलाव करें > प्रोजेक्ट सेटिंग > XR प्लग-इन मैनेजमेंट > ARCore एक्सटेंशन पर जाएं.
2. ज़रूरी सुविधाएं में जाकर, क्लाउड ऐंकर चुनें.

सेशन के कॉन्फ़िगरेशन में क्लाउड ऐंकर की सुविधाएं चालू करना

जब आपके ऐप्लिकेशन में क्लाउड ऐंकर की सुविधा चालू हो जाती है, तो अपने ऐप्लिकेशन के एआर सेशन के कॉन्फ़िगरेशन में, क्लाउड ऐंकर की सुविधा चालू करें, ताकि यह ARCore API के साथ काम कर सके:

1. पक्का करें कि प्रोजेक्ट एसेट फ़ोल्डर में ARCoreExtensionsConfig स्क्रिप्ट वाला ऑब्जेक्ट हो. एसेट बनाने के लिए, एसेट पैनल पर दायां क्लिक करें और बनाएं > XR > ARCore एक्सटेंशन कॉन्फ़िगरेशन चुनें.

2. ARCoreextensionsConfig स्क्रिप्ट वाला ऑब्जेक्ट चुनें और उसे अपने एसेट फ़ोल्डर में चुनें. इसके बाद, Cloud ऐंकर मोड को चालू है पर सेट करें.

   

3. ARCoreExtensionsConfig कॉन्फ़िगरेशन का इस्तेमाल करने के लिए, ARCore एक्सटेंशन गेम ऑब्जेक्ट को कॉन्फ़िगर करें. हैरारकी पैनल में, ARCore एक्सटेंशन गेम ऑब्जेक्ट को ढूंढें जिसे आपने शुरुआत में ARCore एक्सटेंशन सेट अप करते समय बनाया था. साथ ही, ARCore एक्सटेंशन कॉन्फ़िगरेशन फ़ील्ड को ARCoreExtensionsConfig स्क्रिप्ट वाले ऑब्जेक्ट से जोड़ें, ताकि वह आपके एसेट फ़ोल्डर में मौजूद रहे.

   

क्लाउड ऐंकर होस्ट करना

होस्टिंग की शुरुआत ARAnchorManager.HostCloudAnchorAsync() को कॉल से होती है. ARCore, विज़ुअल डेटा, डिवाइस के पोज़, और ARCore एपीआई को ऐंकर पोज़िशन में अपलोड करेगा. इसके बाद, एपीआई इस जानकारी को प्रोसेस करके 3D फ़ीचर मैप बनाता है. इसके बाद, यह डिवाइस पर ऐंकर के लिए एक खास क्लाउड ऐंकर आईडी लौटाता है.

ARCore क्लाउड ऐंकर मैनेजमेंट एपीआई का इस्तेमाल करके, होस्ट किए गए ऐंकर की लाइफ़ को भी बढ़ाया जा सकता है.

किसी क्लाउड ऐंकर को पूरी तरह से होस्ट करने के लिए, आपके ऐप्लिकेशन को यह तरीका अपनाना होगा:

1. ARAnchorManager.HostCloudAnchorAsync() को कॉल करें.
2. जब तक वादे का नतीजा नहीं मिलता, तब तक कोरूटीन शुरू करें. ज़्यादा जानकारी के लिए, Unity में कोरूटीन देखें.
3. गड़बड़ी ठीक न होने पर, गड़बड़ी के कोड को समझें और देखें कि क्या नतीजे की स्थिति है.
4. नतीजे के साथ Cloud ऐंकर आईडी को अन्य क्लाइंट के साथ शेयर करें और ARAnchorManagerExtensions.ResolveCloudAnchorAsync() का इस्तेमाल करके, इसका इस्तेमाल क्लाउड ऐंकर को ठीक करने के लिए करें.

फ़ीचर पॉइंट की मैपिंग क्वालिटी की जांच करना

ARCoreExtensions.FeatureMapQuality किसी कैमरा पोज़ से पिछले कुछ सेकंड में ARCore की देखी गई सुविधाओं के पॉइंट की क्वालिटी दिखाता है. आम तौर पर, अच्छी क्वालिटी की सुविधाओं का इस्तेमाल करके होस्ट किए गए क्लाउड ऐंकर ज़्यादा सटीक तरीके से काम करते हैं. कैमरे के पोज़ के लिए फ़ीचर मैप की क्वालिटी का अनुमान लगाने के लिए, ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() का इस्तेमाल करें.

वैल्यू	जानकारी
Insufficient	पिछले कुछ सेकंड में, पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी अच्छी नहीं थी. यह स्थिति बताती है कि ARCore को क्लाउड ऐंकर को ठीक करने में ज़्यादा मुश्किल होगी. उपयोगकर्ता को डिवाइस को एक जगह से दूसरी जगह ले जाने के लिए बढ़ावा दें, ताकि वे जिस क्लाउड ऐंकर को होस्ट करना चाहते हैं उसे अलग-अलग ऐंगल से देखा जा सके.
Sufficient	ऐसा हो सकता है कि पिछले कुछ सेकंड में पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी, ARCore के लिए क्लाउड ऐंकर को सही तरीके से हल करने के लिए काफ़ी हो. हालांकि, हल किए गए पोज़िशन के सटीक होने की संभावना कम हो जाएगी. उपयोगकर्ता को डिवाइस को एक जगह से दूसरी जगह ले जाने के लिए बढ़ावा दें, ताकि वे जिस क्लाउड ऐंकर को होस्ट करना चाहते हैं उसे अलग-अलग ऐंगल से देखा जा सके.
Good	ऐसा हो सकता है कि पिछले कुछ सेकंड में पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी, ज़्यादा सटीक होने के लिए क्लाउड ऐंकर को सही तरीके से हल करने के लिए काफ़ी हो.

पहले से होस्ट किए गए ऐंकर को ठीक करना

होस्ट किए गए क्लाउड ऐंकर को ठीक करने के लिए, ARAnchorManagerExtensions.ResolveCloudAnchorAsync() को कॉल करें. ARCore API, समय-समय पर ऐंकर की 3D सुविधा वाले मैप से विज़ुअल सुविधाओं की तुलना करता है. ऐसा करके वह ऐंकर की तुलना में उपयोगकर्ता की जगह और ओरिएंटेशन की जानकारी देता है. इसमें मिलते-जुलते शब्द मिलने पर, एपीआई होस्ट किए गए क्लाउड ऐंकर की पोज़ दिखाता है.

एक क्रम में कई क्लाउड ऐंकर के लिए, रिज़ॉल्व शुरू किया जा सकता है. एक समय में ज़्यादा से ज़्यादा 40 क्लाउड ऐंकर कार्रवाइयां मौजूद हो सकती हैं.

किसी कार्रवाई को रद्द करें या क्लाउड ऐंकर को हटाएं

ARCloudAnchor.OnDestroy() अपने-आप तब कॉल किया जाता है, जब ARCloudAnchor कॉम्पोनेंट को शामिल किए गए गेम ऑब्जेक्ट से हटा दिया जाता है. इससे, दिए गए नेटिव क्लाउड ऐंकर ऑब्जेक्ट को अलग कर दिया जाएगा और रिलीज़ कर दिया जाएगा.

किसी क्लाउड ऐंकर कार्रवाई के नतीजे की स्थिति देखना

CloudAnchorState का इस्तेमाल करके, होस्टिंग के नतीजे की स्थिति देखें या गड़बड़ियों को ठीक करने की कार्रवाई ठीक करें.

वैल्यू	जानकारी
ErrorResolvingCloudIdNotFound	समाधान नहीं हो सका, क्योंकि ARCore API को, दिया गया Cloud ऐंकर आईडी नहीं मिला.
ErrorHostingDatasetProcessingFailed	होस्टिंग नहीं हो सकी, क्योंकि सर्वर दिए गए ऐंकर के लिए डेटासेट को प्रोसेस नहीं कर सका. डिवाइस के लिए, एनवायरमेंट से ज़्यादा डेटा इकट्ठा करने के बाद फिर से कोशिश करें.
ErrorHostingServiceUnavailable	ARCore एपीआई को ऐक्सेस नहीं किया जा सका. ऐसा कई कारणों से हो सकता है. हो सकता है कि डिवाइस, हवाई जहाज़ मोड में हो या इंटरनेट कनेक्शन काम न कर रहा हो. ऐसा हो सकता है कि सर्वर को भेजे गए अनुरोध का समय खत्म हो गया हो और कोई जवाब न मिला हो. नेटवर्क कनेक्शन खराब होने, डीएनएस की उपलब्धता, फ़ायरवॉल से जुड़ी समस्याएं या ऐसी कोई भी अन्य वजह हो सकती है जो ARCore एपीआई से कनेक्ट करने के लिए डिवाइस की क्षमता पर असर डाल सकती है.
ErrorInternal	इस ऐंकर के लिए होस्ट करने या उससे जुड़ी समस्या हल करने के लिए, इंटरनल गड़बड़ी का मैसेज मिला. ऐप्लिकेशन को इस गड़बड़ी को वापस पाने की कोशिश नहीं करनी चाहिए.
ErrorNotAuthorized	अनुमति देने की गलत अनुमति की वजह से, ऐप्लिकेशन ARCore एपीआई से संपर्क नहीं कर सकता. अनुमति पाने की मान्य रणनीति के लिए, प्रोजेक्ट सेटिंग > XR > ARCore एक्सटेंशन देखें.
ErrorResolvingPackageTooNew	क्लाउड ऐंकर को ठीक नहीं किया जा सका, क्योंकि क्लाउड ऐंकर को ठीक करने के लिए इस्तेमाल किया गया ARCore एक्सटेंशन पैकेज, पैकेज वर्शन से नया है. साथ ही, इसे होस्ट करने के लिए इस्तेमाल किए जा रहे वर्शन के साथ काम नहीं करता.
ErrorResolvingPackageTooOld	क्लाउड ऐंकर को ठीक नहीं किया जा सका, क्योंकि इसका इस्तेमाल करने के लिए इस्तेमाल किया जाने वाला ARCore एक्सटेंशन पैकेज, इससे पुराने वर्शन के साथ काम नहीं करता. साथ ही, होस्ट करने के लिए इस्तेमाल किए जाने वाले वर्शन के साथ काम नहीं करता.
ErrorResourceExhausted	इस ऐप्लिकेशन ने Google Cloud के दिए गए प्रोजेक्ट के लिए, अनुरोध करने की तय सीमा पूरी कर ली है. आपको Google Developers Console से, अपने प्रोजेक्ट के लिए ARCore API के लिए अतिरिक्त कोटा का अनुरोध करना चाहिए.
Success	इस ऐंकर के लिए होस्ट करने वाला या हटाया गया टास्क पूरा हो गया.

होस्ट के लिए एपीआई कोटा और अनुरोधों का समाधान करना

अनुरोध की बैंडविड्थ के लिए, ARCore API में ये कोटा होते हैं:

कोटा किस तरह का है	ज़्यादा से ज़्यादा	कुल समय	इस पर लागू होता है
ऐंकर की संख्या	अनलिमिटेड	लागू नहीं	प्रोजेक्ट
ऐंकर होस्ट के अनुरोध	30	मिनट	आईपी पता और प्रोजेक्ट
ऐंकर ने समाधान किया है	300	मिनट	आईपी पता और प्रोजेक्ट

अच्छे उपयोगकर्ता अनुभव के लिए सबसे सही तरीके

उपयोगकर्ताओं को ऐप्लिकेशन पर अच्छा उपयोगकर्ता अनुभव देने के लिए, ये काम करें:

• ऐंकर को होस्ट करने से पहले, सेशन शुरू होने के कुछ सेकंड इंतज़ार करें (कोई ऑब्जेक्ट वगैरह रखकर). इससे ट्रैकिंग को स्थिर होने में कुछ समय लगता है.
• ऐंकर होस्ट करने के लिए किसी जगह को चुनते समय, विज़ुअल की सुविधाओं वाली जगह को एक-दूसरे से आसानी से अलग करने की कोशिश करें. सबसे अच्छे नतीजों के लिए, परछाई वाली सतहों या ऐसी जगहों से बचें जहां विज़ुअल की सुविधा नहीं होती है. जैसे: खाली सफ़ेद दीवारें.

• कैमरे को अपनी पसंदीदा जगह के हिसाब से ट्रेनिंग दें और आस-पास की चीज़ों को तय करने के लिए, आस-पास की चीज़ों को ध्यान में रखें. साथ ही, आस-पास की जगहों को करीब-करीब एक जैसी रखें.

• क्लाउड ऐंकर को होस्ट और ठीक करते समय, यह पक्का करें कि असल ज़िंदगी में उन्हें अच्छी रोशनी मिल रही हो.

समर्थन नहीं होने या रोके जाने की नीति

• ARCore SDK टूल 1.12.0 या इसके बाद के वर्शन के साथ बने ऐप्लिकेशन, Cloud ऐंकर API के बंद होने की नीति के तहत आते हैं.
• ARCore SDK 1.11.0 या उससे पहले वाले वर्शन के साथ बनाए गए ऐप्लिकेशन, क्लाउड ऐंकर को होस्ट या ठीक नहीं कर पाते हैं. ऐसा इसलिए होता है, क्योंकि SDK टूल, इस्तेमाल न किए जाने वाले पुराने ARCore API का इस्तेमाल करता है.

आगे क्या

• अपने ऐप्लिकेशन में ARCore का इस्तेमाल करने के ज़्यादा तरीकों के बारे में जानने के लिए, AR Foundation के लिए ARCore एक्सटेंशन से जुड़े दस्तावेज़ का दस्तावेज़ देखें.