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 tin nhắn, các thiết bị lân cận có thể nhận được tin nhắn đó. Hướng dẫn này sẽ hướng dẫn bạn thực hiệ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 cách trao đổi các mã thông báo nhỏ qua Bluetooth. Khi phát hiện thấy một 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 và kiểm tra xem có thông báo nào cần gửi cho nhóm đă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ị, cũng như việc các phương tiện đó có được dùng để truyền mã thông báo và/hoặc quét mã thông báo hay không. Theo mặc định, hoạt động phát và quét được thực hiện trên tất cả các phương tiện. Để khám phá trên một tập hợp con hoặc phương tiện và để kiểm soát việc phát sóng hay quét, bạn phải truyền các tham số bổ sung khi tạo các ấn phẩm và đăng ký.

Khi đang xuất bản và đăng ký, một thông báo "Tính năng Lân cận đang được dùng" sẽ xuất hiện, cho người dùng biết rằng tính năng Lân cận đ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 sử dụng tính năng Lân cận, giúp người dùng có cơ hội tiết kiệm pin nếu không cần dùng tính năng này. Thao tác 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 tính năng Chia sẻ lân cận.
  • Buộc một ứng dụng ngừng sử dụng tính năng Lân cận.
  • Chuyển đến màn hình Cài đặt thiết bị ở gần.

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 dùng API này trong một hoạt động ở nền trước (ngoại trừ BLE background subscribe).

Gọi publish() và/hoặc subscribe() để 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 một thông báo, hãy gọi Nearby.getMessagesClient(Activity).publish() bằng cách truyền mảng byte thông báo của bạn. Bạn nên giữ kích thước của các thông báo dưới 3 KB (chúng tôi có thể gửi các thông báo này nhanh hơn), nhưng chúng tôi có thể hỗ trợ tối đa 100 KB cho những ứng dụng cần kích thước này. 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 cần sử dụng.

Ví dụ sau đây minh hoạ cách gọi publish() để gửi một tin nhắn 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 một thông báo, hãy gọi unpublish(). Ít nhất, ứng dụng của bạn phải gọi hàm unpublish trong phương thức onStop(). Truyền cùng một đối tượng Message đã 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 tin nhắn

Để đăng ký nhận tin nhắn từ các thiết bị khác, hãy gọi Nearby.getMessagesClient(Activity).subscribe(). Bạn sẽ cần truyền một MessageListener để xử lý việc nhận các 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ạ 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 tin nhắn từ thiết bị, hãy gọi đến số Nearby.getMessagesClient(Activity).unsubscribe(). Truyền cùng một đối tượng MessageListener đã 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);
}