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

iOS के लिए Cloud anchor डेवलपर गाइड

क्लाउड ऐंकर की सुविधा देने के लिए, ARKit के iOS इंटरफ़ेस वाले ARCore SDK टूल की मदद से, iOS और Android डिवाइसों के बीच ऐंकर एक ही एनवायरमेंट में शेयर किए जा सकते हैं.

अपने ऐप्लिकेशन में, ARCore API या ARCore Cloud Anchor सेवा का इस्तेमाल करने का तरीका जानें. अगर आप क्लाउड ऐंकर के लिए नए हैं, तो:

अपने ऐप्लिकेशन में क्लाउड ऐंकर चालू करना

क्लाउड ऐंकर एपीआई का इस्तेमाल करने के लिए, आपको एक GARSessionConfiguration बनाना होगा और इसके लिए cloudAnchorMode प्रॉपर्टी सेट करनी होगी, जैसा कि iOS में ARCore सेशन को कॉन्फ़िगर करना है. कॉन्फ़िगरेशन सेट करने के लिए, setConfiguration:error: (GARSession) का इस्तेमाल करें.

आपको अपने Google Cloud Platform प्रोजेक्ट के लिए ARCore API को भी चालू करना होगा.

ऐंकर होस्ट करना और रिज़ॉल्व करना

आप ARCore API से क्लाउड ऐंकर होस्ट कर सकते हैं और उन्हें ठीक कर सकते हैं. एपीआई में, पुष्टि करने के ऐसे तरीके भी शामिल हैं जो पूरे किए गए अनुरोधों पर कॉलबैक देते हैं.

ऐंकर होस्ट करें

ARAnchor को होस्ट करने से, ऐंकर को किसी जगह के लिए, एक जैसे निर्देशांक सिस्टम में रखा जाता है.

होस्ट करने का अनुरोध, Google के सर्वर को विज़ुअल डेटा भेजता है. इससे ARAnchor, मौजूदा जगह के बारे में बताने वाले निर्देशांक सिस्टम में मैप की स्थिति को मैप करता है. यह अनुरोध बिना किसी आईडी के GARAnchor दिखाता है. एक सफल होस्ट अनुरोध, GARAnchor को बाद के GARFrame में एक यूनीक आईडी देता है.

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];
  self.garAnchor = [self.gSession hostCloudAnchor:self.arAnchor error:nil];
  [self enterState:HelloARStateHosting];
}

ऐंकर का समाधान करें

ARAnchor को रिज़ॉल्व करने से, Android और iOS डिवाइसों को किसी फ़िज़िकल स्पेस में दिखाया जा सकता है. इससे, पहले से होस्ट किए गए ऐंकर नए सीन में जुड़ सकते हैं.

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

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  self.garAnchor = [self.gSession resolveCloudAnchorWithIdentifier:identifier error:nil];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be on the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

होस्ट के तरीकों और अनुरोधों का समाधान करने के लिए, डेटा देने के तरीके

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

होस्ट

  • session:didHostAnchor:
  • session:didFailToHostAnchor:

समाधान करें

  • session:didResolveAnchor:
  • session:didFailToResolveAnchor:

-(void)session:(ARSession *)arSession didUpdateFrame:(ARFrame *)arFrame {
  [...]

-(void)session:(GARSession *)garSession didHostAnchor:(GARAnchor *)garAnchor {
  // successful host
}

-(void)session:(GARSession *)garSession didFailToHostAnchor:(GARAnchor *)garAnchor {
  // failed host
}

-(void)session:(GARSession *)garSession didResolveAnchor:(GARAnchor *)garAnchor {
  // successful resolve
}

-(void)session:(GARSession *)garSession didFailToResolveAnchor:(GARAnchor *)garAnchor {
  // failed resolve
}

वैकल्पिक GARSession पोलिंग पैटर्न

अगर आप मेटल का इस्तेमाल कर रहे हैं या आपको पोल करने का विकल्प चाहिए, तो और आपका ऐप्लिकेशन कम से कम 30 FPS (फ़्रेम प्रति सेकंड) पर चले, इस पैटर्न का इस्तेमाल करें, ताकि ARFrame को GARSession पास किया जा सके:

-(void)myOwnPersonalUpdateMethod {
        ARFrame *arFrame = arSession.currentFrame;
        NSError *error = nil;
        GARFrame *garFrame = [garSession update:arFrame error:&error];
        // your update code here
}

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

ARCore v1.20 से पहले, क्लाउड ऐंकर सिर्फ़ होस्ट किए जाने के बाद, 24 घंटे तक ही रिज़ॉल्व किए जा सकते थे. लगातार बनाए जाने वाले क्लाउड ऐंकर की मदद से, अब hostCloudAnchor:error: का इस्तेमाल करके बनाया जा सकता है और एक क्लाउड ऐंकर बनाया जा सकता है. इस लाइव स्ट्रीम में, एक से लेकर 365 दिन तक का समय (TTL) रखा जा सकता है. क्लाउड ऐंकर मैनेजमेंट एपीआई का इस्तेमाल करके, ऐंकर पहले से ही होस्ट किए जाने के बाद, ऐंकर की अवधि भी बढ़ाई जा सकती है.

/**
* This creates a new Cloud Anchor with a given lifetime in days, using the transform
 * of the provided anchor.
 *
 * The cloud state of the returned anchor will be set to GARCloudAnchorStateTaskInProgress and the
 * initial transform will be set to the transform of the provided anchor. However, the returned
 * anchor and the original anchor are independent of one another, and their two transforms
 * may diverge over time.
 *
 * Hosting requires a working Internet connection and an active session where the tracking state
 * is ARTrackingStateNormal. If it is unable to establish a connection to the ARCore Cloud Anchor
 * service, ARCore will continue to silently retry in the background.
 *
 * @param anchor The ARAnchor with the desired transform to be used to create a hosted Cloud
 *     Anchor.
 * @param TTLDays The anchor’s lifetime in days. Must be a positive number. The maximum
 * allowed value is 1 if you are using an API key to authorize the Cloud Anchor API call.
 * Otherwise, the maximum allowed value is 365.
 * @param error Out parameter for an NSError. Possible errors include:
 *     GARSessionErrorCodeInvalidArgument - Invalid (nil) anchor or invalid TTL.
 *     GARSessionErrorCodeNotTracking - Bad current ARTrackingState.
 *     GARSessionErrorCodeResourceExhausted - ARCore tried to create too many Cloud Anchors.
 * @return The new GARAnchor, or nil if there is an error.
 */

- (GARAnchor *_Nullable)hostCloudAnchor:(ARAnchor *)anchor
                                TTLDays:(NSInteger)TTLDays
                                  error:(NSError **)error;

अनुमति देना

आपके ऐप्लिकेशन को क्लाउड ऐंकर एपीआई का इस्तेमाल करने की अनुमति होनी चाहिए. आप JSON वेब टोकन (JWT) या एपीआई कुंजी से पुष्टि करने की सुविधा का इस्तेमाल कर सकते हैं.

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

365 दिनों तक क्लाउड ऐंकर होस्ट करने के लिए, साइन किए गए JSON वेब टोकन (JWT) की अनुमति का इस्तेमाल करें. क्लाउड कुंजी को एक दिन तक होस्ट करने के लिए, एपीआई कुंजी की अनुमति का इस्तेमाल करें.

फ़िलहाल, सिर्फ़ ऐसा टोकन इस्तेमाल किया जाता है जो JWT में हस्ताक्षर करता हो (इसका मतलब है कि JSON सेवा के लिए, Google सेवा खाते से हस्ताक्षर किया गया हो). JWT का परिचय देने के लिए JWT की आधिकारिक वेबसाइट देखें. iOS के लिए JSON वेब टोकन जनरेट करने के लिए, आपके सर्वर पर एक एंडपॉइंट होना ज़रूरी है जो नीचे दी गई ज़रूरी शर्तें पूरी करता हो:

  • अनुमति देने के आपके तरीके से, एंडपॉइंट को सुरक्षित रखना ज़रूरी है.

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

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

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

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 --jwt --json $KEYFILE $AUDIENCE --cache ""

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

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

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

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

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

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

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

सबसे पहले, sessionWithError: का इस्तेमाल करके सेशन बनाएं:

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

जब आपको कोई टोकन मिल जाए, तो उसे setAuthToken: का इस्तेमाल करके सेशन में पास करें.

/**
 * Provide an auth token to authorize your app to use the ARCore Cloud Anchor API. If
 * you used an API key to create the session, ARCore will ignore the token and log an error.
 * Otherwise, it will use the most recent valid auth token that you passed in. Call this
 * method each time you refresh your token.
 *
 * @param authToken The token to use when authorizing your call to the ARCore Cloud Anchor API. This
 *                  must be a nonempty ASCII string with no spaces or control characters. ARCore
 *                  will use this until you pass in another token. Currently, JWTs are the only
 *                  supported token types.
 */
- (void)setAuthToken:(NSString *)authToken;

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

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

  • ARCore, खाली वर्णों या विशेष वर्णों वाले टोकन को अनदेखा कर देता है. अगर आप सेशन में किसी मान्य एपीआई कुंजी का इस्तेमाल करते हैं, तो ARCore सभी टोकन को अनदेखा कर देता है. अगर आपने पहले एपीआई कुंजी का इस्तेमाल किया है और अब आपको इसकी ज़रूरत नहीं है, तो हमारा सुझाव है कि आप Google Developers Console में जाकर इसे मिटा दें. साथ ही, उपयोगकर्ताओं को सबसे नए वर्शन पर माइग्रेट करने के बाद, इसे अपने ऐप्लिकेशन से हटा दें.

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

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

क्लाउड कुंजी को एक दिन तक होस्ट करने के लिए, एपीआई कुंजी की पुष्टि करने के विकल्प का इस्तेमाल करें.

अपने प्रोजेक्ट में एपीआई कुंजी जोड़ने और जोड़ने के लिए, यह तरीका अपनाएं:

  1. एपीआई कुंजी पाने के लिए, Google Cloud Platform Console सहायता केंद्र देखें.

  2. Xcode में, नई एपीआई कुंजी को sessionWithAPIKey:bundleIdentifier:error: के तौर पर पास करें, ताकि उसे आपके प्रोजेक्ट में जोड़ा जा सके:

    NSError *error = nil;
    GARSession *session = [GARSession sessionWithAPIKey:@"your-api-key" bundleIdentifier:nil error:&error];
    

मैप की क्वालिटी

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

/**
 * @param transform The camera transform to use to estimate the mapping quality.
 * @param error Out parameter for an `NSError`. Possible errors:
 *        GARSessionErrorCodeNotTracking - Bad current ARTrackingState.
 * @return The estimated quality of the visual feature points seen
 *        by ARCore in the preceding few seconds and visible from the provided camera
 *        transform.
 */

- (GARFeatureMapQuality)estimateFeatureMapQualityForHosting:(simd_float4x4)transform
                                                      error:(NSError **)error;

एपीआई कोटा

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

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

आम तौर पर होने वाली समस्याएं और समाधान

iOS के लिए ARCore SDK टूल का इस्तेमाल करते समय, कुछ समस्याओं का पता चलता है.

डिफ़ॉल्ट तौर पर सेट की गई सेटिंग की वजह से, बीच में ऐप्लिकेशन बंद हो जाता है

जीपीयू फ़्रेम कैप्चर और मेटल एपीआई की पुष्टि की स्कीम की सेटिंग डिफ़ॉल्ट रूप से चालू होती हैं. इसकी वजह से, कभी-कभी ऐप्लिकेशन के SDK टूल में ही क्रैश हो सकता है.

ऐप्लिकेशन के क्रैश होने की जांच करना

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

समाधान

  1. Product > Scheme > Edit Scheme… पर जाएं

  2. Run टैब खोलें.

  3. अपनी मौजूदा सेटिंग देखने के लिए Options पर क्लिक करें.

  4. पक्का करें कि GPU Frame Capture और Metal API Validation, दोनों बंद हों.

  5. अपना ऐप्लिकेशन बनाएं और उसे चलाएं.

पहले से मालूम समस्याओं के बारे में जानने के लिए Cocoapods CHANGELOG देखें.

सीमाएं

ARCore SDK टूल, ARKit setWorldOrigin(relativeTransform:) तरीके से कॉल नहीं करता.

प्रदर्शन संबंधी विचार

ARCore API चालू करने पर मेमोरी का इस्तेमाल बढ़ जाता है. नेटवर्क का ज़्यादा इस्तेमाल होने और सीपीयू इस्तेमाल करने की वजह से, डिवाइस की बैटरी खर्च बढ़ सकती है.

अगले चरण