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

Nearby Messages là một API phát hành-đăng ký cho phép các thiết bị ở gần trao đổi tải trọng dữ liệu nhỏ. Sau khi một thiết bị phát hành một thông báo, các thiết bị lân cận có thể nhận được thông báo đó. Hướng dẫn này sẽ hướng dẫn bạn về tất cả chức năng mà ứng dụng của bạn phải triển khai để phát hành 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 phát hiện 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ủ Thông báo lân cận để xác thực và kiểm tra xem có thông báo nào cần phân phố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 các phương tiện dùng để khám phá 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 mã thông báo hay không. Theo mặc định, việc truyền tin 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 truyền tin hay 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 phát hành và đăng ký, thông báo "Nearby đang hoạt độ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 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 đến tính năng Gần đây. Ứng dụng này cung cấp cho người dùng các tuỳ 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 Chia sẻ lân cận.
• Chuyển đến màn hình Cài đặt thông tin ở 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 tính năng Gần đây. Khi điều này xảy ra, phương thức onExpired() sẽ được kích hoạt.

Vì các API Thông báo lân cận 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 từ một hoạt động trên nền trước (ngoại trừ đăng ký nền 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 unpublish() và unsubscribe() đố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

Để phát hành một thông báo, hãy gọi Nearby.getMessagesClient(Activity).publish() chuyể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 dưới 3 KB – chúng tôi có thể phân phố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 sẽ 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);
}

Lưu ý: Ví dụ này chưa đặt lệnh gọi lại cho trạng thái của bản phát hành. Để đặt lệnh gọi lại, hãy truyền PublishOptions với PublishCallback hợp lệ khi phát hành. Bạn cũng nên thêm OnFailureListener vào cuối lệnh gọi phát hành. Lệnh gọi này sẽ thông báo cho bạn nếu quá trình phát hành 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ỷ 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 lệnh 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 tin nhắn 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 sẽ 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 phát hành, 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 với 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ý. Lệnh gọi này sẽ thông báo cho bạn nếu lệnh đă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 của thiết bị, hãy gọi 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);
}