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

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

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

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

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

• انتقِل إلى أحد التطبيقات لإيقاف ميزة "المشاركة مع الأجهزة المجاورة".
• فرض إيقاف تطبيق عن استخدام ميزة "مشاركة عن قرب"
• انتقِل إلى شاشة الإعدادات المجاورة.

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

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

اتّصِل بـ publish() و/أو subscribe() لاستخدام Nearby Messages API. يجب أن يكون تطبيقك دائمًا 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);
}