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

يمكن لتطبيقك الاشتراك في مرفقات أجهزة إرسال الإشارات منخفضة الطاقة للبلوتوث (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);
}

يوضح مقتطف الرمز التالي التعامل مع الغرض في صف واحد (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)

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

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

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

يوضح مقتطف الرمز التالي استخدام أداة استماع للرسائل لتحليل الرسائل المُستلَمة من إشارة 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(). عند ضبط هذا الخيار، لن تبدأ واجهة برمجة التطبيقات Nearby Messages API عمليات البحث الكلاسيكية باستخدام البلوتوث. ويؤدي ذلك إلى تحسين وقت الاستجابة لرصد العلامات، لأنّ النظام لا ينتقل بين جميع أنواع عمليات المسح الضوئي المحتملة.
  • لإرفاق حمولة رسالة بإشارة، استخدِم Proximity Beacon API.