प्रकाशित करें और सदस्यता लें

Nearby Messages API, पब्लिश-सब्सक्राइब करने वाला एक एपीआई है. इसकी मदद से, आस-पास मौजूद डिवाइसों के बीच डेटा के छोटे पेलोड शेयर किए जा सकते हैं. जब कोई डिवाइस मैसेज पब्लिश करता है, तो आस-पास मौजूद डिवाइस उस मैसेज को पा सकते हैं. अच्छी परफ़ॉर्मेंस बनाए रखने के लिए, मैसेज का साइज़ छोटा होना चाहिए. इस सेवा का इस्तेमाल, फ़ोटो और वीडियो जैसे बड़े ऑब्जेक्ट शेयर करने के लिए नहीं किया जाता.

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

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

ध्यान दें: इस लाइब्रेरी में मौजूद सभी कॉलबैक, डेलिगेट के बजाय ब्लॉक का इस्तेमाल करते हैं. अपने ब्लॉक लागू करते समय, रिटेन साइकल से बचने के लिए सावधानी बरतें. रिटेन साइकल से बचने के तरीके के बारे में जानने के लिए, Apple का दस्तावेज़ देखें.

यह लाइब्रेरी iOS 7 और इसके बाद के वर्शन पर काम करती है. इसे iOS 8 SDK के साथ बनाया गया है.

मैसेज मैनेजर बनाना

इस कोड से एक मैसेज मैनेजर ऑब्जेक्ट बनता है. इसकी मदद से, पब्लिश और सब्सक्राइब किया जा सकता है. मैसेज शेयर करने के लिए, पुष्टि करने की ज़रूरत नहीं होती. इसलिए, आपको iOS के लिए एक सार्वजनिक एपीआई कुंजी देनी होगी. अपने प्रोजेक्ट के लिए, Google Developers Console की एंट्री का इस्तेमाल करके, एक कुंजी बनाई जा सकती है.

Objective-C

#import <GNSMessages.h>

GNSMessageManager *messageManager =
    [[GNSMessageManager alloc] initWithAPIKey:@"API_KEY"];

Swift

let messageManager = GNSMessageManager(APIKey: "API_KEY")

मैसेज पब्लिश करना

इस कोड स्निपेट में, नाम वाला मैसेज पब्लिश करने का तरीका बताया गया है. जब तक पब्लिकेशन ऑब्जेक्ट मौजूद रहता है, तब तक पब्लिकेशन चालू रहता है. पब्लिश करना बंद करने के लिए, पब्लिकेशन ऑब्जेक्ट को रिलीज़ करें.

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)))

मैसेज के लिए सदस्यता लेना

इस कोड स्निपेट में, पिछले पब्लिकेशन स्निपेट से शेयर किए गए सभी नामों के लिए सदस्यता लेने का तरीका बताया गया है. जब तक सदस्यता ऑब्जेक्ट मौजूद रहते हैं, तब तक सदस्यता चालू रहती है. सदस्यता लेना बंद करने के लिए, सदस्यता ऑब्जेक्ट को रिलीज़ करें.

मैसेज फ़ाउंड हैंडलर को तब कॉल किया जाता है, जब आस-पास मौजूद ऐसे डिवाइसों का पता चलता है जो मैसेज पब्लिश कर रहे होते हैं. मैसेज लॉस्ट हैंडलर को तब कॉल किया जाता है, जब कोई मैसेज अब नहीं दिखता (डिवाइस, रेंज से बाहर चला गया है या अब मैसेज पब्लिश नहीं कर रहा है).

Objective-C

id<GNSSubscription> subscription =
    [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
      // Add the name to a list for display
    }
    messageLostHandler:^(GNSMessage *message) {
      // Remove the name from the list
    }];

Swift

let subscription =
    messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
      // Add the name to a list for display
    },
    messageLostHandler: { (message: GNSMessage?) in
      // Remove the name from the list
    })

डिवाइस खोजने के लिए इस्तेमाल किए जाने वाले मीडियम

डिफ़ॉल्ट रूप से, आस-पास मौजूद डिवाइसों को खोजने के लिए, दोनों मीडियम (ऑडियो और ब्लूटूथ) का इस्तेमाल किया जाएगा. साथ ही, दोनों मीडियम ब्रॉडकास्ट और स्कैन करेंगे. कुछ मामलों में, आपको अपने ऐप्लिकेशन की Info.plist में ये एंट्री जोड़नी होंगी:

• अगर आपका ऐप्लिकेशन ऑडियो का इस्तेमाल करके स्कैन करता है, तो NSMicrophoneUsageDescription जोड़ें. यह एक स्ट्रिंग है, जिसमें यह बताया जाता है कि माइक्रोफ़ोन का इस्तेमाल क्यों किया जाएगा. उदाहरण के लिए, "माइक्रोफ़ोन, आस-पास मौजूद डिवाइसों से मिले, गुमनाम टोकन को सुनता है."

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

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

उदाहरण के लिए, किसी ऐसे सेट-टॉप बॉक्स से कनेक्ट करने के लिए डिज़ाइन किए गए ऐप्लिकेशन को, उसे खोजने के लिए सिर्फ़ ऑडियो पर स्कैन करना होगा जो सिर्फ़ ऑडियो पर ब्रॉडकास्ट कर रहा है. यहां दिए गए स्निपेट में, सिर्फ़ ऑडियो स्कैनिंग का इस्तेमाल करके, उस सेट-टॉप बॉक्स पर मैसेज पब्लिश करने का तरीका बताया गया है:

Objective-C

id<GNSPublication> publication = [messageManager publicationWithMessage:message
    paramsBlock:^(GNSPublicationParams *params) {
      params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
        params.discoveryMediums = kGNSDiscoveryMediumsAudio;
        params.discoveryMode = kGNSDiscoveryModeScan;
      }];
    }];

Swift

let publication = messageManager.publication(with: message,
    paramsBlock: { (params: GNSPublicationParams?) in
      guard let params = params else { return }
      params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
        guard let params = params else { return }
        params.discoveryMediums = .audio
        params.discoveryMode = .scan
      })
    })

डीबग लॉगिंग की सुविधा चालू करना

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

मैसेज मैनेजर बनाने से पहले, आपको इसे चालू करना चाहिए. इस कोड स्निपेट में, डीबग लॉगिंग की सुविधा चालू करने का तरीका बताया गया है:

Objective-C

[GNSMessageManager setDebugLoggingEnabled:YES];

Swift

GNSMessageManager.setDebugLoggingEnabled(true)

Nearby की अनुमति की स्थिति को ट्रैक करना

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

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

Objective-C

GNSPermission *nearbyPermission = [[GNSPermission alloc] initWithChangedHandler:^(BOOL granted) {
  // Update the UI here
}];

Swift

let nearbyPermission = GNSPermission(changedHandler: { (granted: Bool) in
  // Update the UI here
})

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

यहां अनुमति की स्थिति पाने और सेट करने के तरीके का एक उदाहरण दिया गया है.

Objective-C

BOOL permissionState = [GNSPermission isGranted];
[GNSPermission setGranted:!permissionState];  // toggle the state

Swift

let permissionState = GNSPermission.isGranted()
GNSPermission.setGranted(!permissionState)  // toggle the state

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

Nearby पर असर डालने वाली उपयोगकर्ता सेटिंग को ट्रैक करना

अगर उपयोगकर्ता ने माइक्रोफ़ोन का ऐक्सेस नहीं दिया है, ब्लूटूथ की अनुमति नहीं दी है या ब्लूटूथ बंद कर दिया है, तो आस-पास शेयरिंग ठीक से काम नहीं करेगा या हो सकता है कि वह काम ही न करे. ऐसे मामलों में, आपके ऐप्लिकेशन को एक मैसेज दिखाना चाहिए, ताकि उपयोगकर्ता को यह बताया जा सके कि Nearby की कार्रवाइयों में रुकावट आ रही है. यहां दिए गए स्निपेट में, मैसेज मैनेजर बनाते समय हैंडलर पास करके, उपयोगकर्ता की इन सेटिंग के स्टेटस को ट्रैक करने का तरीका बताया गया है:

Objective-C

GNSMessageManager *messageManager = [[GNSMessageManager alloc]
    initWithAPIKey:API_KEY
       paramsBlock:^(GNSMessageManagerParams *params) {
         params.microphonePermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for microphone permission
         };
         params.bluetoothPowerErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth power
         };
         params.bluetoothPermissionErrorHandler = ^(BOOL hasError) {
           // Update the UI for Bluetooth permission
         };
}];

Swift

let messageManager = GNSMessageManager(
         APIKey: API_KEY,
    paramsBlock: { (params: GNSMessageManagerParams?) in
      guard let params = params else { return }
      params.microphonePermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for microphone permission
      }
      params.bluetoothPowerErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth power
      }
      params.bluetoothPermissionErrorHandler = { (hasError: Bool) in
        // Update the UI for Bluetooth permission
      }
    })

Nearby की अनुमति वाले डायलॉग को ओवरराइड करना

आपके पब्लिकेशन और सदस्यताओं में पास किए गए पैरामीटर के आधार पर, iOS, Nearby को काम करने की अनुमति देने से पहले, अलग-अलग अनुमतियां मांग सकता है. उदाहरण के लिए, डिफ़ॉल्ट रणनीति, नज़दीकी अल्ट्रासोनिक ऑडियो पर ट्रांसमिट किए गए डेटा को सुनती है. इसलिए, iOS, माइक्रोफ़ोन का इस्तेमाल करने की अनुमति मांगेगा. ऐसे मामलों में, Nearby एक "प्रीफ़्लाइट" डायलॉग दिखाएगा. इसमें यह बताया जाएगा कि उपयोगकर्ता से अनुमति क्यों मांगी जा रही है.

अगर आपको "प्रीफ़्लाइट" के लिए कोई कस्टम डायलॉग दिखाना है, तो पब्लिकेशन या सदस्यता के पैरामीटर में, permissionRequestHandler पैरामीटर को कस्टम ब्लॉक पर सेट करें. उपयोगकर्ता के जवाब देने के बाद, आपके कस्टम ब्लॉक को permissionHandler ब्लॉक को कॉल करना होगा. यहां दिए गए स्निपेट में, पब्लिकेशन के लिए ऐसा करने का तरीका बताया गया है:

Objective-C

id<GNSPublication> publication =
    [messageManager publicationWithMessage:[GNSMessage messageWithContent:[name dataUsingEncoding:NSUTF8StringEncoding]]
                               paramsBlock:^(GNSPublicationParams *params) {
                                 params.permissionRequestHandler = ^(GNSPermissionHandler permissionHandler) {
                                   // Show your custom dialog here.
                                   // Don't forget to call permissionHandler() with YES or NO when the user dismisses it.
                                 };
                               }];

Swift

let publication =
    messageManager.publication(with: GNSMessage(content: name.data(using: .utf8)),
        paramsBlock: { (params: GNSPublicationParams?) in
          guard let params = params else { return }
          params.permissionRequestHandler = { (permissionHandler: GNSPermissionHandler?) in
            // Show your custom dialog here.
            // Don't forget to call permissionHandler() with true or false when the user dismisses it.
          }
        })

बैकग्राउंड में काम करने की सुविधा

डिवाइस खोजने के लिए बीएलई का इस्तेमाल करने वाले पब्लिकेशन और सदस्यताएं, बैकग्राउंड में काम कर सकती हैं. बैकग्राउंड मोड का इस्तेमाल करने का फ़ैसला लेते समय, आपको इन बातों के बारे में पता होना चाहिए:

• बैकग्राउंड में काम करने की सुविधा के लिए, सिर्फ़ बीएलई मीडियम का इस्तेमाल किया जा सकता है. ऑडियो का इस्तेमाल नहीं किया जा सकता.
• बैकग्राउंड में बीएलई का इस्तेमाल करने पर, बैटरी की खपत बढ़ जाती है. बैटरी की खपत कम होती है, लेकिन बैकग्राउंड मोड का इस्तेमाल करने का फ़ैसला लेने से पहले, आपको इसे मेज़र करना चाहिए.
• iOS, उपयोगकर्ता से बैकग्राउंड में बीएलई के ज़रिए विज्ञापन दिखाने की अनुमति मांगेगा.

किसी पब्लिकेशन या सदस्यता में बैकग्राउंड मोड जोड़ने के लिए, यह तरीका अपनाएं:

• सही तरीके से कॉन्फ़िगर किए गए GNSStrategy ऑब्जेक्ट को पास करके, अपने पब्लिकेशन या सदस्यता में बैकग्राउंड मोड और सिर्फ़ बीएलई की सुविधा चालू करें. यहां दिए गए स्निपेट में, सदस्यता के लिए ऐसा करने का तरीका बताया गया है:

  Objective-C

  id<GNSSubscription> subscription =
      [messageManager subscriptionWithMessageFoundHandler:^(GNSMessage *message) {
        // Add the name to a list for display
      }
      messageLostHandler:^(GNSMessage *message) {
        // Remove the name from the list
      }
      paramsBlock:^(GNSSubscriptionParams *params) {
        params.strategy = [GNSStrategy strategyWithParamsBlock:^(GNSStrategyParams *params) {
          params.allowInBackground = YES;
          params.discoveryMediums = kGNSDiscoveryMediumsBLE;
        }];
      }];
  

  Swift

  let subscription =
      messageManager.subscription(messageFoundHandler: { (message: GNSMessage?) in
        // Add the name to a list for display
      },
      messageLostHandler: { (message: GNSMessage?) in
        // Remove the name from the list
      },
      paramsBlock:{ (params: GNSSubscriptionParams?) in
        guard let params = params else { return }
        params.strategy = GNSStrategy(paramsBlock: { (params: GNSStrategyParams?) in
          guard let params = params else { return }
          params.allowInBackground = true
          params.discoveryMediums = .BLE
        })
      })
  

• अपने ऐप्लिकेशन की Info.plist में ये एंट्री जोड़ें:

  • UIBackgroundModes एंट्री:

    • बैकग्राउंड में बीएलई स्कैन करने के लिए, bluetooth-central. इसकी ज़रूरत सिर्फ़ तब होती है, जब डिवाइस खोजने के मोड में स्कैनिंग शामिल हो. डिफ़ॉल्ट रूप से, ऐसा होता है.
    • बैकग्राउंड में बीएलई के ज़रिए विज्ञापन दिखाने के लिए, bluetooth-peripheral. इसकी ज़रूरत सिर्फ़ तब होती है, जब डिवाइस खोजने के मोड में ब्रॉडकास्टिंग शामिल हो. डिफ़ॉल्ट रूप से, ऐसा होता है.

  • NSBluetoothPeripheralUsageDescription स्ट्रिंग. इसमें यह बताया जाता है कि बीएलई पर विज्ञापन क्यों दिखाया जाएगा. उदाहरण के लिए, "आस-पास मौजूद डिवाइसों को खोजने के लिए, ब्लूटूथ के ज़रिए एक गुमनाम टोकन का विज्ञापन दिखाया जाता है." ज़्यादा जानकारी के लिए, Apple का दस्तावेज़ देखें.

• बैकग्राउंड में काम करते समय, सिस्टम आपके ऐप्लिकेशन को कभी भी बंद कर सकता है. अगर बैकग्राउंड मोड एक ऐसी सेटिंग है जिसे उपयोगकर्ता चालू या बंद कर सकता है, तो आपके ऐप्लिकेशन को यह काम करना चाहिए:

  • जब भी उपयोगकर्ता बैकग्राउंड मोड की वैल्यू बदलता है, तब उसे NSUserDefaults में सेव करें.
  • शुरू होने पर, इसे NSUserDefaults से पढ़ें और अगर बैकग्राउंड मोड चालू है, तो Nearby के पब्लिकेशन और/या सदस्यताओं को वापस लाएं.

बैकग्राउंड में सूचनाएं

अगर आपको यह सुविधा देनी है कि बैकग्राउंड में काम करते समय, सदस्यता को मैसेज मिलने पर आपका ऐप्लिकेशन उपयोगकर्ता को सूचना दे, तो स्थानीय सूचनाओं का इस्तेमाल किया जा सकता है.

इन्हें अपने ऐप्लिकेशन में जोड़ने के लिए, यह तरीका अपनाएं:

• शुरू होने पर, स्थानीय सूचनाओं के लिए रजिस्टर करें:

  Objective-C

  if ([UIApplication instancesRespondToSelector:@selector(registerUserNotificationSettings:)]) {
    [[UIApplication sharedApplication] registerUserNotificationSettings:
        [UIUserNotificationSettings settingsForTypes:
            UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound
                                          categories:nil]];
  }
  

  Swift

  UIApplication.shared.registerUserNotificationSettings(
      UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil))
  

• अपनी सदस्यता के मैसेज-फ़ाउंड हैंडलर में, स्थानीय सूचना भेजें:

  Objective-C

  GNSMessageHandler myMessageFoundHandler = ^(GNSMessage *message) {
      // Send a local notification if not in the foreground.
      if ([UIApplication sharedApplication].applicationState != UIApplicationStateActive) {
        UILocalNotification *localNotification = [[UILocalNotification alloc] init];
        localNotification.alertBody = @"Message received";
        [[UIApplication sharedApplication] presentLocalNotificationNow:localNotification];
      }
      // Process the new message...
    };
  

  Swift

  let myMessageFoundHandler: GNSMessageHandler = { (message: GNSMessage?) in
    // Send a local notification if not in the foreground.
    if UIApplication.shared.applicationState != .active {
      let localNotification = UILocalNotification()
      localNotification.alertBody = "Message received"
      UIApplication.shared.presentLocalNotificationNow(localNotification)
    }
    // Process the new message...
  }