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

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