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 nhỏ của dữ liệu. 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ẽ hướng dẫn bạn tất cả chức năng mà ứng dụng 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 việc 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 đăng ký 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à liệu 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 và để 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 xuất bản và đăng ký, thông báo "Nearby đang được sử dụng" sẽ xuất hiện, thông báo cho người dùng biết 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ừ hoạt động đăng ký ở nền sau 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 của bạn. Bạn nên giữ thông báo dưới 3 KB (những thông báo này chúng tôi có thể 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. Dịch vụ này không dành cho việc trao đổi các đối tượng lớn hơn như ảnh và video.

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

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

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 Message đối tượng đã dùng để xuất bản (mActiveMessage trong ví dụ này).

Ví dụ mã sau đây cho thấy việc 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 cần sử dụng.

Ví dụ sau đây minh hoạ việc đă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 trên thiết bị, hãy gọi Nearby.getMessagesClient(Activity).unsubscribe(). Truyền cùng đối tượng MessageListener đã dùng để đăng ký (mMessageListener trong ví dụ này).

Ví dụ mã sau đây minh hoạ việc huỷ đăng ký:

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