الحصول على رسائل المرشد

يمكن لتطبيقك الاشتراك في مرفقات إشارات البلوتوث منخفض الطاقة (BLE) باستخدام الآلية نفسها المستخدَمة للاشتراك في الرسائل التي تنشرها الأجهزة المجاورة الأخرى. عند الاشتراك، سيتلقى تطبيقك رسائل تلقائية من كل من أجهزة المرشد والأجهزة المجاورة.

الاشتراك في رسائل إشارات BLE

هناك طريقتان يمكن لتطبيقك من خلالهما الاشتراك في رسائل إشارة BLE:

  • في المقدمة، استجابةً لإجراء أو حدث يتخذه المستخدم.
  • في الخلفية، عندما لا يكون تطبيقك قيد التشغيل.

الاشتراك في المقدمة

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

يمكن لتطبيقك تفعيل الاشتراك في المقدّمة من خلال الاتصال Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions) وضبط الخيار Strategy على BLE_ONLY.

يوضح مقتطف الرمز التالي بدء الاشتراك في المقدّمة Nearby.getMessagesClient(Activity).subscribe(MessageListener, SubscribeOptions):

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.");
    SubscribeOptions options = new SubscribeOptions.Builder()
            .setStrategy(Strategy.BLE_ONLY)
            .build();
    Nearby.getMessagesClient(this).subscribe(mMessageListener, options);
}

إذا لم يعد الاشتراك مطلوبًا، يجب إلغاء الاشتراك في التطبيق من خلال الاتصال على Nearby.getMessagesClient(Activity).unsubscribe(MessageListener).

الاشتراك في الخلفية

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

يمكن لتطبيقك بدء اشتراك في الخلفية من خلال الاتصال Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions) وضبط الخيار Strategy على BLE_ONLY.

يوضح مقتطف الرمز التالي بدء اشتراك في الخلفية من خلال استدعاء Nearby.getMessagesClient(Activity).subscribe(PendingIntent, SubscribeOptions).

// Subscribe to messages in the background.
private void backgroundSubscribe() {
    Log.i(TAG, "Subscribing for background updates.");
    SubscribeOptions options = new SubscribeOptions.Builder()
            .setStrategy(Strategy.BLE_ONLY)
            .build();
    Nearby.getMessagesClient(this).subscribe(getPendingIntent(), options);
}

private PendingIntent getPendingIntent() {
    return PendingIntent.getBroadcast(this, 0, new Intent(this, BeaconMessageReceiver.class),
            PendingIntent.FLAG_UPDATE_CURRENT);
}

يوضح مقتطف الرمز التالي التعامل مع intent في فئة BeaconMessageReceiver.

@Override
public void onReceive(Context context, Intent intent) {
    Nearby.getMessagesClient(context).handleIntent(intent, new MessageListener() {
        @Override
        public void onFound(Message message) {
            Log.i(TAG, "Found message via PendingIntent: " + message);
        }

        @Override
        public void onLost(Message message) {
            Log.i(TAG, "Lost message via PendingIntent: " + message);
        }
    });
}

إذا لم يعد الاشتراك مطلوبًا، يجب إلغاء الاشتراك في التطبيق من خلال الاتصال على Nearby.getMessagesClient(Activity).unsubscribe(PendingIntent).

تحليل رسائل المرشد

إشارات المرفقات هي كائن ثنائي كبير من البيانات العشوائية التي يمكنك إضافتها إلى أجهزة المرشد. يتكون كل مرفق من الأجزاء التالية:

  • مساحة الاسم: معرّف مساحة الاسم.
  • النوع: نوع البيانات
  • البيانات: قيمة البيانات للمرفق.

يوضح مقتطف الشفرة التالي استخدام مستمع الرسالة لتحليل الرسائل المستلمة من إشارة BLE:

mMessageListener = new MessageListener() {
    @Override
    public void onFound(Message message) {
        // Do something with the message here.
        Log.i(TAG, "Message found: " + message);
        Log.i(TAG, "Message string: " + new String(message.getContent()));
        Log.i(TAG, "Message namespaced type: " + message.getNamespace() +
                "/" + message.getType());
    }

    ...
};

يعتمد تحليل المحتوى على تنسيق وحدات البايت. يفترض هذا المثال أن وحدات بايت المحتوى تشفِّر سلسلة UTF-8، ولكن رسالة المرشد يمكنها ترميز تنسيقات بايت أخرى (على سبيل المثال، مخزن مؤقت للبروتوكولات المتسلسلة). لمزيد من المعلومات، راجع إضافة المرفقات إلى أجهزة المرشد.

لمعرفة مساحات الاسم المرتبطة بمشروعك، يمكنك طلب namespaces.list.

ملاحظات:

  • للحفاظ على عمر البطارية، يمكنك استدعاء Nearby.getMessagesClient(Activity).unsubscribe() في وظيفة onStop() في نشاطك. يُرجى العِلم أنّ هذا الإجراء لا ينطبق إلا عند الاشتراك في المقدمة.
  • لتقليل وقت الاستجابة، استخدِم الخيار Strategy.BLE_ONLY عند الاتصال بـ Nearby.getMessagesClient(Activity).subscribe(). عند ضبط هذا الخيار، لن تشغِّل واجهة برمجة تطبيقات "الرسائل القريبة" عمليات البحث الكلاسيكية عن البلوتوث. ويساهم ذلك في تحسين وقت الاستجابة لرصد الإشارة، لأنّ النظام لا يتنقل بين جميع أنواع عمليات الفحص الممكنة.
  • لإرفاق حمولة رسالة بالمرشد، استخدِم Proximity Beacon API.