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

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

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

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

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

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

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

ونظرًا إلى احتمال أن تؤثر واجهات برمجة تطبيقات تطبيق "الرسائل القريبة" في عمر البطارية، يجب عدم استخدامها إلا من خلال نشاط يعمل في المقدّمة (باستثناء الاشتراك في الخلفية BLE).

يمكنك الاتصال 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(). من المفترض أن يطلب تطبيقك إلغاء النشر على الأقل بطريقة 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);
}