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

Nearby Messages, पब्लिश-सब्सक्राइब करने वाला एक एपीआई है. इसकी मदद से, आस-पास मौजूद डिवाइसों के बीच डेटा के छोटे पेलोड का लेन-देन किया जा सकता है. जब कोई डिवाइस मैसेज पब्लिश करता है, तो आस-पास के डिवाइसों को वह मैसेज मिल सकता है. इस गाइड में, उन सभी सुविधाओं के बारे में बताया गया है जिन्हें आपके ऐप्लिकेशन को लागू करना होगा. ऐसा Nearby Messages API का इस्तेमाल करके, मैसेज पब्लिश करने और मैसेज पाने के लिए करना होगा.

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

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

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

• 'आस-पास' सुविधा बंद करने के लिए, किसी ऐप्लिकेशन पर जाएं.
• किसी ऐप्लिकेशन को 'आस-पास' सुविधा का इस्तेमाल करने से रोकना.
• आस-पास मौजूद डिवाइसों से कनेक्ट करने की सेटिंग स्क्रीन पर जाएं.

PublishCallback() और SubscribeCallback() का इस्तेमाल करके, उन मामलों के बारे में सुना जा सकता है जब कोई उपयोगकर्ता, ऐप्लिकेशन को आस-पास शेयरिंग की सुविधा का इस्तेमाल करने से रोकता है. ऐसा होने पर, onExpired() तरीका ट्रिगर होता है.

Nearby Messages API से बैटरी लाइफ़ पर असर पड़ सकता है. इसलिए, इनका इस्तेमाल सिर्फ़ फ़ोरग्राउंड ऐक्टिविटी से किया जाना चाहिए. हालांकि, बीएलई बैकग्राउंड सब्सक्राइब के मामले में ऐसा नहीं है.

Nearby Messages API का इस्तेमाल करने के लिए, publish() और/या subscribe() को कॉल करें. आपका ऐप्लिकेशन हमेशा unpublish() और unsubscribe() में onStop() होना चाहिए.

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    mMessageListener = new MessageListener() {
        @Override
        public void onFound(Message message) {
            Log.d(TAG, "Found message: " + new String(message.getContent()));
        }

        @Override
        public void onLost(Message message) {
            Log.d(TAG, "Lost sight of message: " + new String(message.getContent()));
        }
    }

    mMessage = new Message("Hello World".getBytes());
}

@Override
public void onStart() {
    super.onStart();
    ...
    Nearby.getMessagesClient(this).publish(mMessage);
    Nearby.getMessagesClient(this).subscribe(mMessageListener);
}

@Override
public void onStop() {
    Nearby.getMessagesClient(this).unpublish(mMessage);
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
    ...
    super.onStop();
}

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

मैसेज पब्लिश करने के लिए, Nearby.getMessagesClient(Activity).publish() को कॉल करें. साथ ही, मैसेज बाइट ऐरे पास करें. हमारा सुझाव है कि मैसेज का साइज़ 3 केबी से कम रखें. इससे हम मैसेज को तेज़ी से डिलीवर कर सकते हैं. हालांकि, जिन ऐप्लिकेशन को इसकी ज़रूरत होती है उनके लिए हम 100 केबी तक के मैसेज स्वीकार कर सकते हैं. इस सेवा का इस्तेमाल, फ़ोटो और वीडियो जैसे बड़े ऑब्जेक्ट शेयर करने के लिए नहीं किया जाता.

इस्तेमाल की जाने वाली रणनीति सेट करने के लिए, PublishOptions.setStrategy() को कॉल किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है.

यहां दिए गए उदाहरण में, छोटा टेक्स्ट मैसेज भेजने के लिए publish() को कॉल करने का तरीका बताया गया है:

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.getMessagesClient(this).publish(mActiveMessage);
}

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

मैसेज को अप्रकाशित करना

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

यहां दिए गए कोड के उदाहरण में, unpublish() को कॉल करने का तरीका बताया गया है:

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

मैसेज पाने की सुविधा चालू करना

अन्य डिवाइसों से मैसेज पाने की सुविधा के लिए, Nearby.getMessagesClient(Activity).subscribe() पर कॉल करें. सदस्यता वाले मैसेज पाने के लिए, आपको MessageListener पास करना होगा.

इस्तेमाल की जाने वाली रणनीति सेट करने के लिए, SubscribeOptions.setStrategy() को कॉल किया जा सकता है. हालांकि, ऐसा करना ज़रूरी नहीं है.

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

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    ...
    mMessageListener = new MessageListener() {
        @Override
        public void onFound(Message message) {
            Log.d(TAG, "Found message: " + new String(message.getContent()));
        }

        @Override
        public void onLost(Message message) {
            Log.d(TAG, "Lost sight of message: " + new String(message.getContent()));
        }
    }
}

// Subscribe to receive messages.
private void subscribe() {
    Log.i(TAG, "Subscribing.");
    Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}

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

सदस्यता छोड़ें

सदस्यता छोड़ने और डिवाइस से मैसेज पाना बंद करने के लिए, Nearby.getMessagesClient(Activity).unsubscribe() पर कॉल करें. उसी MessageListener ऑब्जेक्ट को पास करें जिसका इस्तेमाल सदस्यता लेने के लिए किया गया था (इस उदाहरण में mMessageListener).

यहां दिए गए कोड के उदाहरण में, सदस्यता छोड़ने का तरीका बताया गया है:

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}