النشر والاشتراك

‫Nearby Messages هي واجهة برمجة تطبيقات للنشر والاشتراك تتيح للأجهزة المجاورة تبادل حمولات صغيرة من البيانات. بعد أن ينشر أحد الأجهزة رسالة، يمكن للأجهزة المجاورة تلقّيها. يرشدك هذا الدليل إلى جميع الوظائف التي يجب أن ينفّذها تطبيقك لنشر الرسائل والاشتراك فيها باستخدام Nearby Messages API.

يتم تحديد مجموعة الأجهزة المجاورة من خلال تبادل رموز صغيرة عبر البلوتوث. عندما يرصد جهاز رمزًا من جهاز مجاور، يرسل الرمز إلى خادم Nearby Messages للتحقّق منه والتحقّق مما إذا كانت هناك أي رسائل يجب تسليمها لمجموعة الاشتراكات الحالية في التطبيق.

يمكن لأي تطبيق التحكّم في مجموعة الوسائط المستخدَمة لاكتشاف الأجهزة، وما إذا كانت الوسائط مستخدَمة لبث الرموز و/أو البحث عنها. يتم تلقائيًا بث الرموز والبحث عنها على جميع الوسائط. لإجراء عملية الاكتشاف على مجموعة فرعية من الوسائط والتحكّم في ما إذا كان سيتم البث أو البحث، يجب تمرير معلّمات إضافية عند إنشاء المنشورات والاشتراكات.

عند النشر والاشتراك بشكل نشط، يظهر إشعار "تطبيق Nearby قيد الاستخدام" لإعلام المستخدمين بأنّ Nearby نشط. لا يظهر هذا الإشعار إلا عندما تستخدم تطبيق واحد أو أكثر Nearby بشكل نشط، ما يمنح المستخدمين فرصة للحفاظ على عمر البطارية إذا لم تكن هناك حاجة إلى Nearby. ويوفّر للمستخدمين الخيارات التالية:

• الانتقال إلى أحد التطبيقات لإيقاف Nearby
• فرض إيقاف تطبيق عن استخدام Nearby
• الانتقال إلى شاشة إعدادات Nearby

يمكنك استخدام PublishCallback() و SubscribeCallback() للاستماع إلى الحالات التي يفرض فيها المستخدم على التطبيق التوقف عن استخدام Nearby. عند حدوث ذلك، يتم تفعيل طريقة onExpired().

بما أنّ Nearby Messages APIs قد تؤثر في عمر البطارية، يجب استخدامها فقط من نشاط في المقدّمة (باستثناء الاشتراك في الخلفية عبر البلوتوث منخفض الطاقة).

استخدِم 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);
}

ملاحظة: لم يتم في هذا المثال ضبط عمليات معاودة الاتصال لحالة النشر. لضبط عملية معاودة الاتصال، مرِّر PublishOptions مع PublishCallback صالح عند النشر. يجب أيضًا إلحاق OnFailureListener بنهاية طلب النشر، ما سيُعلمك في حال تعذُّر النشر. على سبيل المثال، إذا لم يكن الجهاز متصلاً بالإنترنت.

إلغاء نشر رسالة

لإلغاء نشر رسالة، استدعِ unpublish(). يجب أن يستدعي تطبيقك على الأقل 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);
}