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

Ứng dụng Tin nhắn lân cận là một API đăng ký xuất bản, cho phép các thiết bị ở gần trao đổi các tải dữ liệu nhỏ. Sau khi thiết bị đăng 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ẽ chỉ cho bạn 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 Message API (API Thông báo lân cận).

Nhóm 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 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 gửi cho nhóm 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 nhóm phương tiện dùng để khám phá thiết bị, cũng như liệu các phương tiện đó có được dùng để phát đi mã thông báo và/hoặc quét tìm mã thông báo hay không. Theo mặc định, hoạt động phát sóng và quét sẽ đượ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, cũng như kiểm soát việc phát đi thông báo 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 chủ động xuất bản và đăng ký, thông báo "Tính năng lân cận đang được sử dụng" sẽ hiển thị để 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ỉ hiển thị khi một hoặc nhiều ứng dụng đang chủ động sử dụng tính năng Lân cận. Nhờ đó, người dùng có thể tiết kiệm pin nếu không cần sử dụng tính năng Lân cận. Mã 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 Lân cận.
• Chuyển đến màn hình Cài đặt lân cận.

Bạn có thể 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 Lân cận. 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 từ một hoạt động trên nền trước (ngoại trừ việc đăng ký BLE trong nền).

Gọi publish() và/hoặc subscribe() để sử dụng Nearby Message API (API Thông báo lân cận). Ứ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();
}

Đăng thông báo

Để phát hành một thông báo, hãy gọi Nearby.getMessagesClient(Activity).publish() truyền mảng byte của thông báo. Bạn nên giữ cho thông báo có kích thước dưới 3KB – 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 thông báo. 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 minh hoạ việc gọi publish() để gửi một tin nhắn 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 thiết lập lệnh gọi lại cho trạng thái của nội dung xuất bản. Để đặt một lệnh gọi lại, hãy truyền PublishOptions cùng với một 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. Thao tác này sẽ thông báo cho bạn nếu việc phát hành không thành công. Ví dụ như trong trường hợp thiết bị không có kết nối Internet.

Huỷ đăng 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 huỷ xuất bản trong phương thức onStop(). Truyền chính đố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 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 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 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ạ 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);
}

Lưu ý: Tương tự như khi phát hành, bạn có thể đặt một lệnh gọi lại cho trạng thái của gói thuê bao. Truyền SubscribeOptions cùng 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ý. Thao tác này sẽ thông báo cho bạn nếu đăng ký không thành công. Ví dụ như trong trường hợp thiết bị không có kết nối Internet.

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 chính đối tượng MessageListener dùng để đăng ký (trong ví dụ này là mMessageListener).

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

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