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

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

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

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

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

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

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

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

आस-पास के मैसेज भेजने की सुविधा वाले एपीआई का इस्तेमाल करने के लिए, publish() और/या subscribe() को कॉल करें. आपका ऐप्लिकेशन हमेशा onStop() में, unpublish() और unsubscribe() के बीच सममित होना चाहिए.

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

ध्यान दें: इस उदाहरण में, पब्लिश करने की स्थिति के लिए कॉलबैक सेट नहीं किए गए हैं. कॉलबैक सेट करने के लिए, पब्लिश करते समय PublishOptions के साथ मान्य PublishCallback डालें. आपको पब्लिश करने के कॉल के आखिर में 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);
}

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

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

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

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

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