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

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

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

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

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

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

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

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

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