अपने Android एनडीके ऐप्लिकेशन (C) के लिए Geospatial API को चालू करें

अपने ऐप्लिकेशन की सेटिंग कॉन्फ़िगर करें, ताकि वह Geospatial API का इस्तेमाल कर सके.

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

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

अगर आपको यहां दिए गए फ़ंक्शन को दिखाने वाला कोई सैंपल ऐप्लिकेशन चलाना है, तो Java के लिए, Android के लिए ARCore जियोस्पेशियल क्विकस्टार्ट देखें. क्विकस्टार्ट ऐप्लिकेशन का सैंपल ऐप्लिकेशन, Java में लिखा गया है. इस दस्तावेज़ में दिए गए कोड सैंपल उसी फ़ंक्शन के लिए हैं जो C में लिखा गया है.

भौगोलिक एपीआई के बारे में ज़्यादा जानकारी के लिए, भौगोलिक डेटा के एपीआई के बारे में जानकारी देखें.

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

पक्का करें कि आपका डेवलपमेंट एनवायरमेंट, Java के लिए Quickstart में बताई गई ARCore SDK टूल की ज़रूरी शर्तों को पूरा करता है.

ARCore API चालू करना

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

कुंजी के बिना पुष्टि करने की सुविधा को प्राथमिकता दी जाती है, लेकिन एपीआई पासकोड से अनुमति देने की सुविधा भी काम करती है.

अपने ऐप्लिकेशन में ज़रूरी लाइब्रेरी जोड़ना

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

अपने ऐप्लिकेशन की build.gradle फ़ाइल में, Play services की जगह की जानकारी वाली लाइब्रेरी को शामिल करने के लिए, Google Play services को सेट अप करें.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

सेशन के कॉन्फ़िगरेशन में जियोस्पेशियल सुविधाएं चालू करें

सेशन बनाने से पहले, अपने सेशन कॉन्फ़िगरेशन में GeospatialMode को ENABLED में बदलें:

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

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

जब जियोस्पेशियल मोड ENABLED पर सेट होता है, तब ऐप्लिकेशन को विज़ुअल पोज़िशनिंग सिस्टम (वीपीएस) से जगह की जानकारी लेने की अनुमति होती है.

उपयोगकर्ता को डिवाइस के डेटा के इस्तेमाल की अनुमति देने का अनुरोध करें

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

देखें कि डिवाइस पर यह सुविधा काम करती है या नहीं

जैसा कि Java के लिए quickstart में बताया गया है, ARCore के साथ काम करने वाले सभी डिवाइस भी भौगोलिक एपीआई के साथ काम नहीं करते हैं.

यह देखने के लिए कि उपयोगकर्ता के डिवाइस पर यह काम करता है या नहीं, ArSession_isGeospatialModeSupported() पर कॉल करें. अगर यह वैल्यू 'गलत' दिखाता है, तो सेशन को कॉन्फ़िगर करने की कोशिश न करें (नीचे दिया गया है), क्योंकि ऐसा करने पर, ArStatus, AR_ERROR_UNSUPPORTED_CONFIGURATION को रिपोर्ट करेगा.

रनटाइम के दौरान, उपयोगकर्ता से जगह की जानकारी की अनुमतियां मांगें

आपके ऐप्लिकेशन को रनटाइम के दौरान, जगह की जानकारी की अनुमतियां पाने का अनुरोध करना होगा.

ARCore भौगोलिक एपीआई का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को नीचे दी गई अतिरिक्त अनुमतियां रजिस्टर करनी होंगी:

  • ACCESS_FINE_LOCATION का इस्तेमाल करें, ताकि उपयोगकर्ता की जगह की सटीक जानकारी का पता लगाया जा सके.

  • ACCESS_COARSE_LOCATION उपयोगकर्ता की जगह की जानकारी सटीक न होने का पता लगाने और उसकी निजता से जुड़ी ज़रूरी शर्तों का पालन करने के लिए. हालांकि, जियोस्पेशियल एपीआई को अनुमानित जगह की जानकारी के साथ काम करने के लिए कॉन्फ़िगर नहीं किया जा सकता. साथ ही, जब उपयोगकर्ता यह अनुमति सेट कर देगा, तब एपीआई अनुरोध पूरे नहीं हो पाएंगे. ज़्यादा जानकारी के लिए नीचे देखें.

  • ACCESS_INTERNET ARCore Geospatial API की सेवा से संपर्क करें.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Android 12 या इसके बाद के वर्शन वाले डिवाइसों पर, उपयोगकर्ता यह अनुरोध कर सकते हैं कि आपके ऐप्लिकेशन के पास सिर्फ़ जगह की अनुमानित जानकारी की जानकारी हो. यह अनुरोध पूरा करने के लिए, आपके ऐप्लिकेशन में ACCESS_COARSE_LOCATION अनुमति को कॉन्फ़िगर किया जाना चाहिए. साथ ही, ACCESS_FINE_LOCATION अनुमति भी कॉन्फ़िगर की जानी चाहिए, जैसा कि ऊपर दिखाया गया है. आपको जगह की जानकारी की दोनों अनुमतियां कॉन्फ़िगर करनी होंगी.

हालांकि, जब उपयोगकर्ता अनुमानित जगह की जानकारी देते हैं, तो ऐसा करने पर जियोस्पेशियल एपीआई, जगह की सटीक जानकारी नहीं ले पाता. अगर आपका ऐप्लिकेशन सिर्फ़ अनुमानित जगह की जानकारी देता है, तो जियोस्पेशियल सेवा को अपने-आप कॉन्फ़िगर होने की अनुमति नहीं मिलेगी. आपका ऐप्लिकेशन, जगह की अनुमानित जानकारी के साथ भौगोलिक एपीआई का इस्तेमाल नहीं कर सकता.

डिवाइस की मौजूदा जगह पर भौगोलिक डेटा की उपलब्धता देखना

भौगोलिक पोज़ तय करने के लिए Geospatial API, VPS और जीपीएस को एक साथ इस्तेमाल करता है, इसलिए एपीआई का इस्तेमाल तब तक किया जा सकता है, जब तक डिवाइस, जगह की जानकारी देने के लिए तैयार है. जिन इलाकों में जीपीएस की सटीक जानकारी नहीं होती है वहां के लिए, यह एपीआई ज़्यादा सटीक पोज़ जनरेट करने के लिए, वीपीएस कवरेज का इस्तेमाल करेगा. जैसे, इनडोर स्पेस और घना शहरी माहौल. सामान्य स्थितियों में, वीपीएस करीब 5 मीटर की स्थिति सटीक और 5 डिग्री घूमने की सटीक जानकारी दे सकता है. ArSession_checkVpsAvailabilityAsync() का इस्तेमाल करके, पता लगाएं कि दी गई जगह में VPS कवरेज है या नहीं.

भौगोलिक एपीआई का इस्तेमाल उन इलाकों में भी किया जा सकता है जहां वीपीएस कवरेज नहीं है. अगर खुली जगह में हवाई जहाज़ में कोई रुकावट नहीं आती है या आस-पास कोई रुकावट नहीं होती है, तो बेहतर पोज़ बनाने के लिए जीपीएस काफ़ी मददगार हो सकता है.

आगे क्या करना है