Android NDK (C) के लिए Cloud Anchors डेवलपर गाइड

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

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

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

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

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

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

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

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

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

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

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

    डीबग हस्ताक्षर वाले प्रमाणपत्र का फ़िंगरप्रिंट वापस पाने के लिए:

    • अपने Android Studio प्रोजेक्ट में Gradle टूलपैन खोलें.
    • <project-name> > Tasks > android पर जाएं.
    • signreport टास्क को चलाएं.

    • डीबग वैरिएंट के लिए SHA-1 फ़िंगरप्रिंट को Google Cloud Console के SHA-1 सर्टिफ़िकेट फ़िंगरप्रिंट फ़ील्ड में कॉपी करें.
  3. com.google.android.gms:play-services-auth:16+ को अपने ऐप्लिकेशन की डिपेंडेंसी में शामिल करें.

  4. अगर आप ProGuard का इस्तेमाल कर रहे हैं, तो उसे अपने ऐप्लिकेशन की build.gradle फ़ाइल में जोड़ें

    buildTypes {
      release {
        ...
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
      }
    }
    

    अपने ऐप्लिकेशन की proguard-rules.pro फ़ाइल में ये चीज़ें जोड़ें:

    -keep class com.google.android.gms.common.** { *; }
    -keep class com.google.android.gms.auth.** { *; }
    -keep class com.google.android.gms.tasks.** { *; }
    

एपीआई कुंजी की पुष्टि करना

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

  1. नए या मौजूदा Google Cloud Platform प्रोजेक्ट के लिए, ARCore API चालू करें.
  2. Google Cloud Console से इस प्रोजेक्ट के लिए, एपीआई कुंजी पाएं.
  3. Android Studio में, अपने प्रोजेक्ट में नई एपीआई कुंजी जोड़ें. अपने ऐप्लिकेशन के <application> एलिमेंट के <meta-data> एलिमेंट में एपीआई कुंजी शामिल करें:

    <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY"/>
    

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

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

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                                AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

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

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

आप ArSession_hostAndAcquireNewCloudAnchor() को भी 24 घंटे (1 दिन) तक के TTL (टीटीएल) के साथ होस्ट कर सकते हैं या ARCore क्लाउड ऐंकर मैनेजमेंट एपीआई का इस्तेमाल करके, होस्ट किए गए ऐंकर के जीवनकाल को बढ़ा सकते हैं.

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

  1. ArSession_hostAndAcquireNewCloudAnchorWithTtl() पर कॉल करें.
  2. नई स्थिति के लिए, ArAnchor_getCloudAnchorState() पर स्थिति की जांच करते रहें. ऐसा तब तक करें, जब तक उसकी स्थिति SUCCESS न हो.
  3. देखें कि aranchor_acquirecloudanchorid() स्ट्रिंग आइडेंटिफ़ायर दिखाता है या नहीं.
  4. आइडेंटिफ़ायर को दूसरे क्लाइंट के साथ शेयर करें और इसका इस्तेमाल, क्लाउड ऐंकर को ArSession_resolveAndAcquireNewCloudAnchor() के साथ ठीक करने के लिए करें.

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

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

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

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

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

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

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

ट्रैकिंग बंद करने और क्लाउड ऐंकर को हटाने के लिए, ArAnchor_detach() को कॉल करें. ArAnchor_release() को कॉल करके ऐंकर के रेफ़रंस अलग से रिलीज़ किए जाने चाहिए.

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

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

वैल्यू जानकारी
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND समाधान नहीं हो सका, क्योंकि ARCore API को क्लाउड ऐंकर आईडी नहीं मिला.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED होस्टिंग नहीं हो सकी, क्योंकि सर्वर दिए गए ऐंकर के लिए डेटासेट प्रोसेस नहीं कर सका. डिवाइस में पर्यावरण से जुड़ा ज़्यादा डेटा इकट्ठा होने के बाद, फिर से कोशिश करें.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore एपीआई पहुंच के बाहर था. ऐसा कई कारणों से हो सकता है. हो सकता है कि डिवाइस हवाई जहाज़ मोड में हो या उसमें इंटरनेट कनेक्शन काम न कर रहा हो. हो सकता है कि सर्वर को भेजे गए अनुरोध का समय पूरा न हुआ हो. ऐसा हो सकता है कि गलत नेटवर्क कनेक्शन, डीएनएस की उपलब्धता, फ़ायरवॉल से जुड़ी समस्याएं या ऐसी कोई भी वजह हो जिससे डिवाइस की ARCore API से कनेक्ट होने में परेशानी हो रही हो.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL इस ऐंकर के लिए, होस्ट करने या पूरा करने का काम एक अंदरूनी गड़बड़ी के साथ पूरा हुआ. ऐप्लिकेशन को इस गड़बड़ी से ठीक करने की कोशिश नहीं करनी चाहिए.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED ऐप्लिकेशन से मिली अनुमति मान्य नहीं है.
  • हो सकता है कि Google Cloud प्रोजेक्ट में ARCore एपीआई चालू न हो या जिस कार्रवाई की आप कोशिश कर रहे हैं उसकी अनुमति नहीं है.
  • अगर एपीआई कुंजी के अनुमति का इस्तेमाल किया जाता है: मेनिफ़ेस्ट में एपीआई कुंजी अमान्य है, बिना अनुमति के है या मौजूद नहीं है. अगर एपीआई कुंजी, मौजूदा ऐप्लिकेशन को शामिल न करने वाले ऐप्लिकेशन पर सेट हो, तो हो सकता है कि वह काम न करे.
  • कीलेस की अनुमति का इस्तेमाल किए जाने पर: आप OAuth क्लाइंट नहीं बना पाए.
  • 'Google Play सेवाएं' इंस्टॉल नहीं की गई हैं या यह बहुत पुराना है या किसी वजह से ठीक से काम नहीं कर रही है (उदाहरण के लिए, मेमोरी दबाव की वजह से सेवाओं का बंद होना).
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW क्लाउड ऐंकर को ठीक नहीं किया जा सका, क्योंकि ऐंकर को ठीक करने के लिए इस्तेमाल किया गया SDK वर्शन इससे नया है. इसलिए, इसे होस्ट करने के लिए इस्तेमाल किए गए वर्शन से मेल नहीं खाता.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD क्लाउड ऐंकर को ठीक नहीं किया जा सका, क्योंकि ऐंकर को ठीक करने के लिए इस्तेमाल किया गया SDK वर्शन इससे पुराना है. इसलिए, इसे होस्ट करने के लिए इस्तेमाल किए गए वर्शन से मेल नहीं खाता.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED ऐप्लिकेशन ने दिए गए Google Cloud प्रोजेक्ट के लिए तय किया गया अनुरोध कोटा खत्म कर दिया है. आपको Google Developers Console से अपने प्रोजेक्ट के लिए ARCore API के लिए अतिरिक्त कोटा का अनुरोध करना चाहिए.
AR_CLOUD_ANCHOR_STATE_NONE ऐंकर पूरी तरह से स्थानीय है. इसे कभी भी ArSession_hostAndAcquireNewCloudAnchor() का इस्तेमाल करके होस्ट नहीं किया गया है. ArSession_resolveAndAcquireNewCloudAnchor() का इस्तेमाल करके, इसका समाधान नहीं किया गया है.
AR_CLOUD_ANCHOR_STATE_SUCCESS इस ऐंकर के लिए, एक होस्टिंग या टास्क पूरा किया गया.
AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS ऐंकर को होस्ट करने या उसे ठीक करने का काम जारी है. टास्क के बैकग्राउंड में पूरा होने के बाद, अगले कॉल ArSession_update() पर ऐंकर को एक नया स्टेटस मिलता है.

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

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

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

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

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

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

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

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

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

आगे क्या