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ẽ giúp bạn tìm hiểu 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 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 và kiểm tra xem có thông báo nào cần gửi cho nhóm gói thuê bao hiện tại của ứng dụng hay không.

Ứng dụng có thể kiểm soát tập hợp phương tiện dùng để phát hiện thiết bị và liệu các phương tiện đó có được dùng để truyền phát mã thông báo và/hoặc quét tìm mã thông báo hay không. Theo mặc định, việc truyền 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 nhóm nhỏ 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 thêm các tham số 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 is in use" (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 sử dụng tính năng Gần đây, 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 Gần đây. Tham số 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 Thiết bị ở gần.
• Buộc một ứng dụng ngừng sử dụng Nearby.
• Chuyển đến màn hình Cài đặt tính năng Chia sẻ lân cậ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ỉ nên sử dụng các API này trong một hoạt động trên nền trước (ngoại trừ đăng ký BLE ở chế độ nền).

Gọi publish() và/hoặc subscribe() để sử dụng Nearby Messages API. Ứng dụng của bạn phải luôn unpublish() và unsubscribe() một cách đối xứng 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(), truyền mảng byte thông báo của bạn. Bạn nên giữ cho thông báo có kích thước nhỏ hơn 3 KB (chúng tôi có thể gửi những 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 đến. Dịch vụ này không dùng để 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ạ 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);
}

Lưu ý: Ví dụ này chưa đặt lệnh gọi lại cho trạng thái xuất bản. Để đặt lệnh gọi lại, hãy truyền PublishOptions bằng PublishCallback hợp lệ khi xuất bản. Bạn cũng nên thêm OnFailureListener vào cuối lệnh gọi xuất bản để nhận thông báo nếu quá trình xuất bản không thành công. Ví dụ: nếu thiết bị không có kết nối Internet đang hoạt động.

Hủy xuất bản thông báo

Để huỷ xuất bản một thông báo, hãy gọi unpublish(). Ứng dụng của bạn phải gọi ít nhất là phương thức huỷ phát hành trong phương thức onStop(). Truyền cùng một đối tượng Message đã được dùng để phát hành (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 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 tin nhắn đã đă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);
}

Lưu ý: Giống như khi xuất bản, bạn có thể đặt lệnh gọi lại cho trạng thái của gói thuê bao. Truyền SubscribeOptions bằng SubscribeCallback hợp lệ khi đăng ký. Bạn cũng nên thêm OnFailureListener vào cuối lệnh gọi đăng ký để nhận thông báo nếu lệnh gọi đăng ký không thành công. Ví dụ: nếu thiết bị không có kết nối Internet đang hoạt động.

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 đã được 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);
}