अपने iOS ऐप्लिकेशन के लिए जियोस्पेशल एपीआई चालू करें

अपने ऐप्लिकेशन की सेटिंग कॉन्फ़िगर करें, ताकि यह भौगोलिक डेटा के एपीआई का इस्तेमाल कर सके.

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

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

अगर आप यहां दिए गए फ़ंक्शन के बारे में बताने वाला सैंपल ऐप्लिकेशन चलाना चाहते हैं, तो iOS के लिए ARCore जियोस्पेशल क्विकस्टार्ट देखें.

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

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

अपने ऐप्लिकेशन में ARCore SDK टूल जोड़ना

अपने ऐप्लिकेशन के लिए Podfile को अपडेट करें, ताकि इसमें ARCore SDK टूल और iOS के साथ काम करने वाले वर्शन शामिल किए जा सकें. इसके लिए:

  1. platform और pod को अपने प्रोजेक्ट की Podfile में जोड़ें:

    platform :ios, '11.0'
    pod 'ARCore/Geospatial', '~> 1.35.0'
    

    अगर आपको iOS 10 के साथ काम करना है, तो platform :ios, '10.0' का विकल्प भी दिया जा सकता है. हालांकि, जियोस्पेशल एपीआई सिर्फ़ iOS >= 11 पर रनटाइम के दौरान काम करेगा.

  2. टर्मिनल विंडो खोलें और उस फ़ोल्डर से pod install को चलाएं जहां आपका Xcode प्रोजेक्ट मौजूद है.

    इससे एक .xcworkspace फ़ाइल जनरेट होती है जिसका इस्तेमाल ऐप्लिकेशन बनाने और चलाने के लिए किया जाता है.

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

ARCore API चालू करें

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

अनुमति देने का तरीका सेट अप करें

भौगोलिक डेटा को वीपीएस पर कॉल करने के लिए, आपके ऐप्लिकेशन को अनुमति की ज़रूरत होगी. हस्ताक्षर किए गए JSON वेब टोकन (JWT) या एपीआई कुंजी के इस्तेमाल की अनुमति दी जा सकती है.

टोकन (JWT पर हस्ताक्षर किया गया) की अनुमति

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

ARCore, (JSON वेब टोकन) का इस्तेमाल करके iOS में एपीआई कॉल की अनुमति देता है. टोकन पर Google सेवा खाते से हस्ताक्षर होना चाहिए.

iOS के लिए टोकन जनरेट करने के लिए, आपके सर्वर पर एक एंडपॉइंट होना चाहिए, जो नीचे दी गई ज़रूरी शर्तें पूरी करता हो:

  • आपके अनुमति देने के तरीके को एंडपॉइंट को सुरक्षित करना चाहिए.

  • एंडपॉइंट को हर बार एक नया टोकन जनरेट करना होगा, जैसे:

    • हर उपयोगकर्ता को एक खास टोकन मिलता है.
    • टोकन की समयसीमा तुरंत खत्म नहीं होती.

सेवा खाता और साइनिंग कुंजी बनाना

Google सेवा खाता बनाने और साइन इन करने के लिए यह तरीका अपनाएं:

  1. Google Cloud Platform Console के नेविगेशन मेन्यू में, APIs & Services > Credentials पर जाएं.

  2. अपने हिसाब से प्रोजेक्ट चुनें. इसके बाद, Create Credentials > Service account पर क्लिक करें.

  3. Service account details में जाकर, नए खाते के लिए कोई नाम लिखें. इसके बाद, Create पर क्लिक करें.

  4. Service account permissions पेज पर, Select a role ड्रॉपडाउन पर जाएं. Service Accounts > Service Account Token Creator चुनें, फिर Continue पर क्लिक करें.

  5. Grant users access to this service account पेज पर, Done पर क्लिक करें.

    इससे, आपको APIs & Services > Credentials पर वापस ले जाया जाएगा.

  6. Credentials पेज पर, नीचे Service Accounts सेक्शन तक स्क्रोल करें और उस खाते के नाम पर क्लिक करें जिसे आपने अभी-अभी बनाया है.

  7. Service account details पेज पर, नीचे स्क्रोल करके Keys सेक्शन पर जाएं और Add Key > Create new key को चुनें.

  8. JSON को कुंजी के टाइप के तौर पर चुनें और Create पर क्लिक करें.

    ऐसा करने पर, एक JSON फ़ाइल डाउनलोड हो जाएगी, जिसमें आपकी मशीन के लिए निजी कुंजी मौजूद होगी. JSON फ़ाइल के डाउनलोड किए गए हिस्से को सुरक्षित जगह पर सेव करें.

अपने सर्वर पर टोकन बनाएं

अपने सर्वर पर नए टोकन (JWT) बनाने के लिए, स्टैंडर्ड JWT लाइब्रेरी और उस JSON फ़ाइल का इस्तेमाल करें जिसे आपने अपने नए सेवा खाते से सुरक्षित तरीके से डाउनलोड किया था.

अपनी डेवलपमेंट मशीन पर टोकन बनाना

अपनी डेवलपमेंट मशीन पर JWT जनरेट करने के लिए, oauth2l निर्देश का इस्तेमाल करें:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

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

टोकन पर हस्ताक्षर करें

JWT पर हस्ताक्षर करने के लिए, आपको RS256 एल्गोरिदम और इन दावों का इस्तेमाल करना होगा:

  • iss — सेवा खाते का ईमेल पता.
  • sub — सेवा खाते का ईमेल पता.
  • iat — टोकन जनरेट होने के दौरान, सेकंड में Unix समय.
  • expiat + 3600 (1 घंटा). टोकन की समयसीमा, सेकंड में खत्म होती है.
  • aud — दर्शक. ऑडियंस इस पर सेट होनी चाहिए https://arcore.googleapis.com/.

JWT पेलोड में गैर-मानक दावों की ज़रूरत नहीं होती है, हालांकि uid दावे संबंधित उपयोगकर्ता की पहचान करने के लिए उपयोगी हो सकते हैं.

अगर आप अपने JWT को जनरेट करने के लिए किसी दूसरे तरीके का इस्तेमाल करते हैं, जैसे कि Google की ओर से मैनेज किए जाने वाले माहौल में Google API का इस्तेमाल करना, तो इस सेक्शन में किए गए दावों से अपने JWT पर हस्ताक्षर करना न भूलें. सबसे पहले, पक्का करें कि ऑडियंस सही है.

ARCore सेशन में टोकन पास करें

ARCore सेशन, ARCore भौगोलिक डेटा एपीआई का मुख्य एंट्री पॉइंट है. भौगोलिक डेटा एपीआई का इस्तेमाल करने के लिए, आपको एक GARSessionConfiguration बनाना होगा और इसके लिए geospatialMode प्रॉपर्टी सेट करनी होगी, जैसा कि iOS में ARCore सेशन को कॉन्फ़िगर करने में बताया गया है.

  1. sessionWithError: का इस्तेमाल करके, सेशन बनाएं और टोकन में पास करें:

    NSError *error = nil;
    GARSession *session = [GARSession sessionWithError:&error];
    

    ARCore SDK टूल से अनुमति देते समय, टोकन में कोई खाली जगह या ASCII स्ट्रिंग नहीं होनी चाहिए. इसमें कोई खाली जगह या कंट्रोल वर्ण नहीं होने चाहिए. जब तक आप दूसरा टोकन पास नहीं कर लेते, तब तक ARCore इसका इस्तेमाल करेगा.

    जब आपको कोई टोकन मिल जाए, तो उसे setAuthToken: का इस्तेमाल करके सेशन में पास करें. ऐसा नहीं होने पर, इस सेशन में आपके हाल ही के मान्य ऑथराइज़ेशन टोकन का इस्तेमाल किया जाएगा. अपना टोकन रीफ़्रेश करने पर हर बार इस तरीके से कॉल करें:

    - (void)setAuthToken:(NSString *)authToken;
    
  2. GARSessionConfiguration बनाएं और उसके लिए geospatialMode प्रॉपर्टी सेट करें.

  3. कॉन्फ़िगरेशन सेट करने के लिए, setConfiguration:error: (GARSession) का इस्तेमाल करें.

सेशन में टोकन पास करने पर, इन बातों का ध्यान रखें:

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

    अगर अब आपको API (एपीआई) कुंजी की ज़रूरत नहीं है, तो उसे Google Developers Console में से मिटाएं और उसे अपने ऐप्लिकेशन से हटाएं.

  • ARCore, ऐसे टोकन को अनदेखा कर देता है जिनमें स्पेस या विशेष वर्ण शामिल होते हैं.

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

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

एपीआई कुंजी पाएं

  1. अपने Google Cloud प्रोजेक्ट में, एपीआई कुंजी पाएं, जैसा कि एपीआई कुंजी बनाना में बताया गया है.

  2. एपीआई कुंजी को कॉपी करें, जैसा कि बाद में चिपकाएं.

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

    आपको प्रतिबंधित एपीआई कुंजियों के लिए बंडल आईडी भी बताना होगा.

एपीआई कुंजी की मदद से ARCore सेशन बनाएं

ARCore सेशन, ARCore भौगोलिक डेटा एपीआई का मुख्य एंट्री पॉइंट है. भौगोलिक डेटा का एपीआई इस्तेमाल करने के लिए, आपको geospatialMode प्रॉपर्टी के साथ एक GARSessionConfiguration बनाना होगा, जैसा कि iOS में ARCore सेशन को कॉन्फ़िगर करना है:

  • GARSessionConfiguration बनाएं और इसके लिए geospatialMode प्रॉपर्टी सेट करें.

  • कॉन्फ़िगरेशन सेट करने के लिए, setConfiguration:error: (GARSession) का इस्तेमाल करें.

Xcode में, अपने ऐप्लिकेशन में, अपनी एपीआई कुंजी को GARSession में जोड़ें. नीचे दिए गए उदाहरण की तरह, अपने Google Cloud प्रोजेक्ट से कॉपी की गई एपीआई कुंजी चिपकाएं:

self.garSession = [GARSession sessionWithAPIKey:@"your-api-key"
                               bundleIdentifier:nil
                                          error:&error];

सेशन के कॉन्फ़िगरेशन में भौगोलिक सुविधाओं को चालू करें

यह देखना कि आपके डिवाइस पर, Android ऐप्लिकेशन काम करता है या नहीं

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

डिवाइस की जांच करने के लिए GARSession.isGeospatialModeSupported: का इस्तेमाल करें, जैसा कि यहां बताया गया है:

if (![self.garSession isGeospatialModeSupported:GARGeospatialModeEnabled]) {
  [self setErrorStatus:@"GARGeospatialModeEnabled is not supported on this device."];
  return;
}

GARSessionConfiguration *configuration = [[GARSessionConfiguration alloc] init];
configuration.geospatialMode = GARGeospatialModeEnabled;
[self.garSession setConfiguration:configuration error:&error];
if (error) {
  [self setErrorStatus:[NSString stringWithFormat:@"Failed to configure GARSession: %d",
                                                  (int)error.code]];
  return;
}

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

सत्र कॉन्फ़िगर करने से पहले, रनटाइम के समय आपके ऐप्लिकेशन को नीचे दी गई स्थान अनुमतियों का अनुरोध करना होगा:

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

इसलिए, भौगोलिक डेटा को तय करने के लिए जियोस्पेशल एपीआई को वीपीएस और जीपीएस का इस्तेमाल करना पड़ता है. इसलिए, एपीआई का इस्तेमाल तब तक किया जा सकता है, जब तक डिवाइस अपनी जगह की जानकारी का पता लगा सकता है. जीपीएस की सटीक जानकारी न देने वाले इलाके, जैसे कि इनडोर और घने शहरी माहौल में एपीआई, सटीक कन्वर्ज़न जनरेट करने के लिए वीपीएस कवरेज पर निर्भर करेगा. सामान्य स्थितियों में, वीपीएस से करीब 5 मीटर की सटीक जगह की जानकारी और 5 डिग्री तक घुमाव तय किया जा सकता है. GARSession.checkVPSAvailabilityAtCoordinate:completionHandler: का इस्तेमाल करके, यह तय करें कि किसी जगह पर वीपीएस कवरेज है या नहीं.

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

आगे क्या