Xuất bản và đăng ký

Nearby Messages là một API xuất bản-đăng ký cho phép các thiết bị ở gần trao đổi các tải trọng dữ liệu nhỏ. Sau khi một thiết bị xuất bản thông báo, các thiết bị ở gần có thể nhận được thông báo đó. Hướng dẫn này sẽ trình bày tất cả chức năng mà ứng dụng của bạn phải triển khai để xuất bản thông báo và đăng ký nhận thông báo bằng Nearby Messages API.

Tập hợp các thiết bị ở gần được xác định bằng cách trao đổi các mã thông báo nhỏ qua Bluetooth. Khi một thiết bị phát hiện thấy mã thông báo từ một thiết bị ở gần, thiết bị đó sẽ gửi mã thông báo đến máy chủ Nearby Messages để xác thực mã thông báo và kiểm tra xem có thông báo nào cần gửi cho tập hợp gói thuê bao hiện tại của ứng dụng hay không.

Một ứng dụng có thể kiểm soát tập hợp các phương tiện được dùng để phát hiện thiết bị, và kiểm soát việc các phương tiện có được dùng để phát mã thông báo và/hoặc quét mã thông báo hay không. Theo mặc định, quá trình phát và quét được thực hiện trên tất cả các phương tiện. Để phát hiện trên một tập hợp con hoặc các phương tiện, cũng như để kiểm soát việc phát hoặc quét, bạn phải truyền các tham số bổ sung khi tạo ấn bản và gói thuê bao.

Khi đang tích cực xuất bản và đăng ký, một thông báo "Nearby đang được sử dụng" sẽ xuất hiện để thông báo cho người dùng rằng Nearby đang hoạt động. Thông báo này chỉ xuất hiện khi một hoặc nhiều ứng dụng đang tích cực sử dụng Nearby, giúp người dùng có cơ hội tiết kiệm pin nếu không cần dùng Nearby. Thông báo này cung cấp cho người dùng các lựa chọn sau:

  • Chuyển đến một ứng dụng để tắt Nearby.
  • Buộc một ứng dụng ngừng sử dụng Nearby.
  • Chuyển đến màn hình Cài đặt Nearby.

Bạn có thể sử dụng PublishCallback() và SubscribeCallback() để theo dõi các trường hợp người dùng buộc ứng dụng ngừng sử dụng Nearby. Khi điều này xảy ra, phương thức onExpired() sẽ được kích hoạt.

Vì Nearby Messages API có khả năng ảnh hưởng đến thời lượng pin, nên bạn chỉ được sử dụng các API này từ một hoạt động ở nền trước (ngoại trừ tính năng đăng ký ở nền sau bằng BLE).

Gọi publish() và/hoặc subscribe() để sử dụng Nearby Messages API. Ứng dụng của bạn phải luôn đối xứng unpublish() và unsubscribe() trong 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();
}

Xuất bản thông báo

Để xuất bản thông báo, hãy gọi Nearby.getMessagesClient(Activity).publish() truyền mảng byte thông báo. Bạn nên giữ thông báo ở mức dưới 3 KB (những thông báo này có thể được gửi nhanh hơn), nhưng chúng tôi có thể hỗ trợ tối đa 100 KB cho các ứng dụng cần đến. Dịch vụ này không dùng để trao đổi các đối tượng lớn hơn, chẳng hạn như ảnh và video.

Bạn có thể tuỳ ý gọi PublishOptions.setStrategy() để đặt chiến lược sử dụng.

Ví dụ sau đây minh hoạ cách gọi publish() để gửi một thông báo văn bản nhỏ:

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

Huỷ xuất bản thông báo

Để huỷ xuất bản thông báo, hãy gọi unpublish(). Ít nhất thì ứng dụng của bạn phải gọi huỷ xuất bản trong phương thức onStop(). Truyền cùng một Message đối tượng đã dùng để xuất bản (mActiveMessage trong ví dụ này).

Ví dụ về mã sau đây cho thấy cách gọi unpublish():

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

Đăng ký nhận thông báo

Để đăng ký nhận thông báo từ các thiết bị khác, hãy gọi Nearby.getMessagesClient(Activity).subscribe(). Bạn cần truyền một MessageListener để xử lý việc nhận thông báo đã đăng ký.

Bạn có thể tuỳ ý gọi SubscribeOptions.setStrategy() để đặt chiến lược sử dụng.

Ví dụ sau đây minh hoạ cách đăng ký nhận thông báo:

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);
}

Huỷ đăng ký

Để huỷ đăng ký và ngừng nhận thông báo thiết bị, hãy gọi Nearby.getMessagesClient(Activity).unsubscribe(). Truyền cùng một MessageListener đối tượng đã dùng để đăng ký (mMessageListener trong ví dụ này).

Ví dụ về mã sau đây minh hoạ cách huỷ đăng ký:

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