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

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)

आस-पास सुविधा की अनुमति की स्थिति ट्रैक करना

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

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

आस-पास को प्रभावित करने वाली उपयोगकर्ता सेटिंग को ट्रैक करना

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

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
      }
    })

आस-पास सुविधा की अनुमति वाले डायलॉग को ओवरराइड करना

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

अगर आपको पसंद के मुताबिक "प्रीफ़्लाइट" डायलॉग बॉक्स देना है, तो पब्लिकेशन या सदस्यता के पैरामीटर में 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.
          }
        })

बैकग्राउंड में होने वाली कार्रवाई

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

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

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

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

  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 एंट्री:

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

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

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

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

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

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

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

• स्टार्टअप पर स्थानीय सूचनाओं के लिए रजिस्टर करें:

  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...
  }