अपने ऐप्लिकेशन में Geospatial API सेट अप करना

इस्तेमाल किए जा सकने वाले XR डिवाइस

इन दिशा-निर्देशों से आपको इस तरह के एक्सआर डिवाइसों के लिए अनुभव तैयार करने में मदद मिलती है.

एक्सआर डिवाइस के टाइप के बारे में जानें →

एक्सआर डिवाइस के टाइप के बारे में जानें →

अपने ऐप्लिकेशन में Geospatial API का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को Google Cloud पर ARCore API को ऐक्सेस करने के लिए सेट अप किया जाना चाहिए. इस एपीआई में विज़ुअल पोज़िशनिंग सर्विस शामिल है. यह Google Street View के डेटा का इस्तेमाल करके, जगह की सटीक जानकारी देती है.

इस गाइड की मदद से, ऐसा Google Cloud प्रोजेक्ट सेट अप किया जा सकता है जिसमें सही एपीआई और एपीआई को ऐक्सेस करने के लिए अनुमति देने के तरीके चालू हों.

Google Cloud प्रोजेक्ट सेट अप करना या किसी मौजूदा प्रोजेक्ट का इस्तेमाल करना

अगर आपके पास कोई मौजूदा Google Cloud प्रोजेक्ट है, तो उसे चुनें.

प्रोजेक्ट सिलेक्टर पर जाएं

अगर आपके पास कोई मौजूदा प्रोजेक्ट नहीं है, तो एक नया प्रोजेक्ट बनाएं.

नया प्रोजेक्ट बनाना

ARCore API चालू करना

ARCore API का इस्तेमाल करने के लिए, आपको इसे अपने प्रोजेक्ट में चालू करना होगा.

ARCore API को चालू करना

Google Cloud के लिए अनुमति सेट अप करना

कोई Android ऐप्लिकेशन, अनुमति देने के दो अलग-अलग तरीकों का इस्तेमाल करके, ARCore API के साथ कम्यूनिकेट कर सकता है: बिना पासकोड के अनुमति देना (OAuth 2.0), जो कि सुझाया गया तरीका है और एपीआई पासकोड से अनुमति देना:

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

• एपीआई पासकोड एक स्ट्रिंग होती है, जिससे Google Cloud प्रोजेक्ट की पहचान होती है. आम तौर पर, एपीआई पासकोड को सुरक्षित नहीं माना जाता, क्योंकि क्लाइंट इन्हें ऐक्सेस कर सकते हैं. ARCore API के साथ कम्यूनिकेट करने के लिए, बिना पासकोड के अनुमति देने की सुविधा का इस्तेमाल करें.

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

ज़रूरी अनुमतियों का अनुरोध करना

Jetpack XR के साथ ARCore में Geospatial API का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को रनटाइम की ये अनुमतियां मांगनी होंगी:

• ACCESS_FINE_LOCATION: उपयोगकर्ता की जगह की सटीक जानकारी का पता लगाने के लिए ज़रूरी है.

मोबाइल डिवाइसों पर, Geospatial API के लिए ये अनुमतियां भी ज़रूरी हैं:

• android.permission.CAMERA: डिवाइस के कैमरे को ऐक्सेस करने के लिए ज़रूरी है.
• android.permission.INTERNET: Google Cloud की सेवाओं के साथ कम्यूनिकेट करने के लिए ज़रूरी है.

सेशन ऐक्सेस करना

Jetpack XR रनटाइम Session की मदद से, जियोस्पेशल जानकारी ऐक्सेस करें. इसे आपके ऐप्लिकेशन को बनाना होगा.

सेशन को कॉन्फ़िगर करना

Geospatial API, एक्सआर सेशन पर डिफ़ॉल्ट रूप से चालू नहीं होता है. आपके ऐप्लिकेशन को Session पर GeospatialMode को कॉन्फ़िगर करके, इसे साफ़ तौर पर चालू करना होगा. ये मोड उपलब्ध हैं:

• GeospatialMode.SPATIAL: Geospatial API चालू है. Geospatial API, डिवाइस के जियोस्पेशल पोज़ का पता लगाने के लिए, विज़ुअल पोज़िशनिंग सिस्टम (वीपीएस), ग्लोबल पोज़िशनिंग सिस्टम (जीपीएस) डेटा, और डिवाइस के मोशन सेंसर का इस्तेमाल करता है. यह मोड, इंटेलिजेंट आईवियर डिवाइसों पर उपलब्ध नहीं है.
• GeospatialMode.INERTIAL: Geospatial API, बैटरी बचाने वाले मोड में चालू है. Geospatial API, डिवाइस के जियोस्पेशल पोज़ का पता लगाने के लिए, सिर्फ़ जीपीएस और डिवाइस के मोशन सेंसर का इस्तेमाल करता है. यह मोड सिर्फ़ इंटेलिजेंट आईवियर डिवाइसों पर उपलब्ध है.
• GeospatialMode.DISABLED: Geospatial API बंद है. किसी दूसरे मोड से इस मोड पर स्विच करने पर, Geospatial API सभी संसाधनों को रिलीज़ कर देता है और ट्रैकिंग बंद कर देता है.

सभी डिवाइसों पर, सभी जियोस्पेशल मोड काम नहीं करते. ज़्यादा जानकारी के लिए, GeospatialMode पर जाएं. XrDevice.isGeospatialSupported का इस्तेमाल करके देखें कि दिया गया GeospatialMode काम करता है या नहीं.

नीचे दिए गए कोड सैंपल में, Session.configure का इस्तेमाल करके GeospatialMode सेट करने का तरीका बताया गया है.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

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

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

जियोस्पेशल ऑब्जेक्ट का इस्तेमाल करना

सेशन कॉन्फ़िगर होने के बाद, Geospatial.getInstance का इस्तेमाल करके Geospatial ऑब्जेक्ट पाएं. Geospatial ऑब्जेक्ट का इस्तेमाल सिर्फ़ तब करें, जब उसकी स्थिति GeospatialTrackingState.RUNNING हो.

यहां दिए गए कोड सैंपल में, Geospatial.state का इस्तेमाल करके, जियोस्पेशल स्टेट को मॉनिटर करने का तरीका बताया गया है.

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

सटीक वैल्यू को समझना

Geospatial API चालू होने पर, यह सटीक जानकारी की तीन वैल्यू देता है: हॉरिज़ॉन्टल, वर्टिकल, और ओरिएंटेशन की सटीक जानकारी. सटीकता की ये वैल्यू समय के साथ अपडेट होती हैं. साथ ही, ज़्यादा डेटा मिलने पर इन्हें और सटीक बनाया जा सकता है. ज़्यादा वैल्यू का मतलब है कि सटीक जानकारी कम है. इन्हें 68% कॉन्फ़िडेंस लेवल के दायरे के तौर पर तय किया जाता है. दूसरे शब्दों में, इस बात की 68% संभावना है कि असल वैल्यू, अनुमानित वैल्यू के दिए गए रेडियस के अंदर हो.

सटीक जानकारी की मौजूदा वैल्यू पाने के लिए, Geospatial.State.horizontalAccuracy, verticalAccuracy, और orientationYawAccuracy का इस्तेमाल करें.

ऐसा हो सकता है कि आपके ऐप्लिकेशन को सही तरीके से काम करने के लिए, जगह की सटीक जानकारी की ज़रूरत हो. उदाहरण के लिए, हो सकता है कि आपका ऐप्लिकेशन वर्चुअल कॉन्टेंट रेंडर करने से पहले, हॉरिज़ॉन्टल ऐक्युरेसी के पांच मीटर से कम होने का इंतज़ार करे. ज़्यादा सटीक डेटा पाने की संभावना बढ़ाने के लिए, आपके ऐप्लिकेशन को उपयोगकर्ताओं को अपने आस-पास देखने का निर्देश देना चाहिए. इसके लिए, उन्हें इमारतों या अन्य सुविधाओं को देखने के लिए कहें जिनकी विज़ुअल जानकारी Google Street View में मौजूद है. Geospatial.checkVpsAvailability का इस्तेमाल करके, यह पता लगाएं कि दी गई जगह पर वीपीएस उपलब्ध है या नहीं.

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

ऐप्लिकेशन में Geospatial API को सही तरीके से सेट अप करने पर, आपका ऐप्लिकेशन ये काम कर सकता है:

• डिवाइस-लोकल पोज़ और जियोस्पेशल पोज़ के बीच कन्वर्ज़न करना,
• जियोस्पेशल पोज़ पर कॉन्टेंट रेंडर करना