เผยแพร่และสมัครรับข้อมูล

Nearby Messages เป็น API แบบเผยแพร่และสมัครรับข้อมูล ซึ่งช่วยให้อุปกรณ์ที่อยู่ใกล้เคียงแลกเปลี่ยนข้อมูลเพย์โหลดขนาดเล็กได้ เมื่ออุปกรณ์เผยแพร่ข้อความแล้ว อุปกรณ์ที่อยู่ใกล้เคียงจะรับข้อความนั้นได้ คู่มือนี้จะอธิบายฟังก์ชันการทำงานทั้งหมดที่แอปของคุณต้องใช้เพื่อเผยแพร่ข้อความและสมัครรับข้อความโดยใช้ Nearby Messages API

ชุดอุปกรณ์ที่อยู่ใกล้เคียงจะกำหนดโดยการแลกเปลี่ยนโทเค็นขนาดเล็กผ่านบลูทูธ เมื่ออุปกรณ์ตรวจพบโทเค็นจากอุปกรณ์ที่อยู่ใกล้เคียง ก็จะส่งโทเค็นไปยังเซิร์ฟเวอร์การรับส่งข้อความใกล้เคียงเพื่อตรวจสอบและดูว่ามีข้อความใดที่ต้องนำส่งสำหรับชุดการสมัครใช้บริการปัจจุบันของแอปพลิเคชันหรือไม่

แอปพลิเคชันสามารถควบคุมชุดสื่อที่ใช้สำหรับการค้นหาอุปกรณ์ รวมถึงควบคุมได้ว่าจะใช้สื่อเพื่อกระจายโทเค็นและ/หรือสแกนหาโทเค็นหรือไม่ โดยค่าเริ่มต้น ระบบจะออกอากาศและสแกนในสื่อทั้งหมด หากต้องการทําการค้นพบในชุดย่อยหรือสื่อ และเพื่อควบคุมว่าจะออกอากาศหรือสแกน คุณต้องส่งพารามิเตอร์เพิ่มเติมเมื่อสร้างสิ่งพิมพ์และการติดตาม

เมื่อเผยแพร่และติดตามอยู่ ระบบจะแสดงการแจ้งเตือน "กำลังใช้ Nearby" เพื่อแจ้งให้ผู้ใช้ทราบว่า Nearby ทำงานอยู่ การแจ้งเตือนนี้จะแสดงขึ้นก็ต่อเมื่อแอปอย่างน้อย 1 แอปกำลังใช้ฟีเจอร์ "บริเวณใกล้เคียง" อยู่ ซึ่งจะช่วยให้ผู้ใช้สามารถยืดอายุการใช้งานแบตเตอรี่ได้หากไม่จำเป็นต้องใช้ฟีเจอร์นี้ โดยจะมีตัวเลือกต่อไปนี้ให้ผู้ใช้

  • ไปที่แอปเพื่อปิดใช้ Nearby
  • บังคับให้แอปหยุดใช้ Nearby
  • ไปที่หน้าจอการตั้งค่าอุปกรณ์ที่อยู่ใกล้เคียง

คุณสามารถใช้ PublishCallback() และ SubscribeCallback() เพื่อฟังเหตุการณ์เมื่อผู้ใช้บังคับให้แอปหยุดใช้ฟีเจอร์ "บริเวณใกล้เคียง" เมื่อเกิดเหตุการณ์นี้ขึ้น ระบบจะเรียกใช้เมธอด onExpired()

เนื่องจาก Nearby Messages API มีแนวโน้มที่จะส่งผลต่ออายุการใช้งานแบตเตอรี่ คุณจึงควรใช้ API ดังกล่าวจากกิจกรรมที่ทำงานอยู่เบื้องหน้าเท่านั้น (ยกเว้นการสมัครใช้บริการ 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 KB เนื่องจากข้อความเหล่านี้จะส่งได้เร็วขึ้น แต่เรารองรับข้อความที่มีขนาดไม่เกิน 100 KB สำหรับแอปที่ต้องการ บริการนี้ไม่ได้มีไว้สำหรับการแลกเปลี่ยนวัตถุขนาดใหญ่ เช่น รูปภาพและวิดีโอ

คุณอาจเรียกใช้ PublishOptions.setStrategy() เพื่อตั้งค่ากลยุทธ์ที่จะใช้

ตัวอย่างต่อไปนี้แสดงการเรียก publish() เพื่อส่งข้อความแบบข้อความสั้นๆ

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.getMessagesClient(this).publish(mActiveMessage);
}

เลิกเผยแพร่ข้อความ

หากต้องการเลิกเผยแพร่ข้อความ ให้กด 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);
}

ยกเลิกการสมัคร

หากต้องการยกเลิกการสมัครรับข้อมูลและหยุดรับข้อความจากอุปกรณ์ ให้โทรไปที่ Nearby.getMessagesClient(Activity).unsubscribe() ส่งออบเจ็กต์ MessageListener เดียวกันกับที่ใช้สมัครใช้บริการ (mMessageListener ในตัวอย่างนี้)

ตัวอย่างโค้ดต่อไปนี้แสดงการยกเลิกการติดตาม

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}