पुराने ARCore Cloud Anchor API का इस्तेमाल रोक दिया गया है. यह 31 अगस्त, 2023 के बाद काम नहीं करेगा. अगर आपका ऐप्लिकेशन इस एपीआई का इस्तेमाल कर रहा है, तो आपको जल्द से जल्द नए ARCore API एंडपॉइंट का इस्तेमाल करने के लिए, इसे अपडेट करना होगा.

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

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

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

आगे बढ़ने से पहले, पक्का करें कि एआर (ऑगमेंटेड रिएलिटी) के बुनियादी सिद्धांतों और एआरकोर सेशन को कॉन्फ़िगर करने का तरीका समझ लिया गया हो.

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

ARCore API चालू करें

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

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

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

कीलेस ऑथराइज़ेशन

1 और 365 दिनों के बीच TTL (टीटीएल) वाले क्लाउड ऐंकर को होस्ट करने और उनका समाधान करने के लिए, बिना अनुमति के इस्तेमाल करें.

ARCore SDK 1.24.0 या बाद के वर्शन के साथ बनाए गए नए Unity प्रोजेक्ट के लिए, डिफ़ॉल्ट रूप से अनुमति देने की रणनीति DoNotUse है. ऐसा इसलिए किया जाता है, ताकि ऐप्लिकेशन को ग़ैर-ज़रूरी लाइब्रेरी से न बनाया जा सके. अगर आपका ऐप्लिकेशन, क्लाउड ऐंकर का इस्तेमाल करता है और उसे ARCore SDK 1.24.0 या इसके बाद वाले वर्शन का इस्तेमाल करके बनाया गया है, तो आपको प्रोजेक्ट सेटिंग > XR प्लग-इन मैनेजमेंट > ARCore एक्सटेंशन में मैन्युअल तरीके से अनुमति चालू करनी होगी.

  1. बदलाव करें > प्रोजेक्ट सेटिंग > XR प्लग-इन प्रबंधन > ARCore एक्सटेंशन पर जाएं और Android की पुष्टि करने की रणनीति ड्रॉप-डाउन मेन्यू से, बिना चाबी का विकल्प चुनें.

    इससे पिछली Cloud kers सेटिंग से स्टोर की गई सभी एपीआई कुंजी मिट जाती है और उसमें ज़रूरी डिपेंडेंसी और ProGuard अपवाद जुड़ जाते हैं. अगर आपने पहले किसी एपीआई कुंजी का इस्तेमाल किया था और अब आपको इसकी ज़रूरत नहीं है, तो हमारा सुझाव है कि आप उसे Google Cloud Platform Console से मिटा दें. साथ ही, उपयोगकर्ताओं को सबसे नए वर्शन पर माइग्रेट करने के बाद उसे अपने ऐप्लिकेशन से हटा दें.

  2. SHA-1 फ़िंगरप्रिंट साइनिंग कुंजी जनरेट करें.

    1. Edit मेन्यू से, Project Settings > Player > Publishing Settings को चुनें.

    2. Keystore Manager पर क्लिक करें और एक नई कुंजी बनाएं.

    3. SHA-1 फ़िंगरप्रिंट साइनिंग कुंजी कॉपी करें (इसे बाद के चरण में चिपकाया जाएगा).

  3. ऐप्लिकेशन के ऐप्लिकेशन आईडी और हस्ताक्षर प्रमाणपत्र SHA-1 फ़िंगरप्रिंट का उपयोग करके Google Cloud Console में अपने Android ऐप्लिकेशन के लिए एक OAuth क्लाइंट आईडी बनाएं. इससे, Android ऐप्लिकेशन को आपके Google Cloud Platform प्रोजेक्ट से जोड़ा जाता है.

एपीआई कुंजी को अनुमति देना

24 घंटे (1 दिन) तक TTL (टीटीएल) वाले क्लाउड ऐंकर को होस्ट करने और उनका समाधान करने के लिए, एपीआई कुंजी की अनुमति का इस्तेमाल करें.

ARCore SDK 1.24.0 या बाद के वर्शन के साथ बनाए गए नए Unity प्रोजेक्ट के लिए, डिफ़ॉल्ट रूप से अनुमति देने की रणनीति DoNotUse है. ऐसा इसलिए किया जाता है, ताकि ऐप्लिकेशन को ग़ैर-ज़रूरी लाइब्रेरी से न बनाया जा सके. अगर आपका ऐप्लिकेशन, क्लाउड ऐंकर का इस्तेमाल करता है और उसे ARCore SDK 1.24.0 या इसके बाद वाले वर्शन का इस्तेमाल करके बनाया गया है, तो आपको प्रोजेक्ट सेटिंग > XR प्लग-इन मैनेजमेंट > ARCore एक्सटेंशन में मैन्युअल तरीके से अनुमति चालू करनी होगी.

  1. बदलाव करें > प्रोजेक्ट सेटिंग > XR प्लग-इन प्रबंधन > ARCore एक्सटेंशन पर जाएं और Android की पुष्टि करने की रणनीति ड्रॉप-डाउन मेन्यू से, एपीआई कुंजी विकल्प चुनें.

  2. Google Cloud Console से इस प्रोजेक्ट के लिए एपीआई कुंजी पाएं.

  3. बदलाव करें > प्रोजेक्ट सेटिंग > XR प्लग-इन मैनेजमेंट > ARCore एक्सटेंशन पर जाएं और अपनी एपीआई कुंजी को Cloud ऐंकर API कुंजियां फ़ील्ड में जोड़ें.

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

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

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

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

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

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

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

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

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

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

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

  1. ARAnchorManager.HostCloudAnchor() को कॉल करें.
  2. जब तक राज्य SUCCESS न हो जाए, तब तक ARCloud ऐंकर.cloudAnchorState() की मदद से, नए ऐंकर की स्थिति को लगातार देखें.
  3. जांच करें कि cloudanchorid() स्ट्रिंग आइडेंटिफ़ायर दिखाता हो.
  4. आइडेंटिफ़ायर को दूसरे क्लाइंट के साथ शेयर करें और इसका इस्तेमाल ARAnchorManagerExtensions.ResolveCloudAnchorId() के साथ क्लाउड ऐंकर की समस्या हल करने के लिए करें.

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

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

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

पहले से होस्ट किए गए ऐंकर से जुड़ी समस्या हल करना

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

आप क्रम से कई क्लाउड ऐंकर के लिए, समाधान शुरू कर सकते हैं. ज़्यादा से ज़्यादा 40 क्लाउड ऐंकर की समस्या एक साथ हल की जा सकती है.

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

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

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

होस्ट किए गए ऐंकर की स्थिति देखने या गड़बड़ियों के अनुरोध के साथ-साथ गड़बड़ियों को ठीक करने के लिए, ARCloud ऐंकर.cloudAnchorState() का इस्तेमाल करें.

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

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

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

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

उपयोगकर्ता को बेहतर अनुभव देने के सबसे सही तरीके

आपके ऐप्लिकेशन का इस्तेमाल करने वाले लोगों को बेहतर अनुभव देने के लिए, नीचे बताए गए काम करने के निर्देश दें:

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

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

समर्थन रोकने की नीति

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

अगला कदम क्या है