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

Nearby Messages là một API đăng ký xuất bản, cho phép trao đổi các thiết bị lân cận tải trọng dữ liệu nhỏ. Sau khi một thiết bị đăng thông báo, các thiết bị ở gần có thể nhận được tin nhắn. 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 để có thể đăng 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ã thông báo từ một thiết bị lân cận, thiết bị đó sẽ gửi mã thông báo đến máy chủ Nearby Message (Thông báo lân cận) để xác thực và kiểm tra xem có thông báo để gửi cho nhóm thuê bao hiện tại của ứng dụ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ị, và liệu phương tiện được dùng để truyền 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 phát sóng và quét được thực hiện trên tất cả các phương tiện. Việc cần làm phát hiện trên một tập hợp con hoặc phương tiện cũng như để kiểm soát xem nên phát hay quét, bạn phải truyền các thông 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" thông báo hiển thị để thông báo cho người dùng rằng tính năng Lân cận đang hoạt động. Thông báo này là chỉ hiển thị khi một hoặc nhiều ứng dụng đang sử dụng tính năng Lân cận, cung cấp cho người dùng cơ hội tiết kiệm pin nếu không cần tính năng Lân cận. Chiến dịch này cung cấp người dùng với các tuỳ chọn sau:

  • Di chuyển đến một ứng dụng để tắt tính năng 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ể sử dụng PublishCallback() và SubscribeCallback() để theo dõi các trường hợp khi người dùng buộc ứng dụng ngừng sử dụng tính năng Lân cận. Khi việc này xảy ra, onExpired() được kích hoạt.

Vì Nearby Messages API có khả năng ảnh hưởng đến thời lượng pin, chúng chỉ nên được dùng từ một hoạt động trên nền trước (ngoại trừ Đăng ký trong 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 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();
}

Đăng thông báo

Để phát hành một thông báo, hãy gọi lệnh Nearby.getMessagesClient(Activity).publish() truyền mảng byte thông báo của bạn. Bạn nên giữ tin nhắn sao cho 3KB--chúng tôi có thể gửi các tin nhắn nhanh hơn--nhưng chúng tôi có thể hỗ trợ tối đa 100KB cho các ứng dụng cần đến. Dịch vụ này không dành cho việc trao đổi những đối tượng lớn hơn như làm ảnh và video.

Bạn có thể gọi PublishOptions.setStrategy() (không bắt buộc) để đặt chiến lược để sử dụng.

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

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 một thông báo

Để huỷ xuất bản một thông báo, hãy gọi unpublish(). Tối thiểu, ứng dụng phải gọi lệnh huỷ xuất bản trong onStop() . Truyền cùng một Message đối tượng dùng để xuất bản (trong ví dụ này là mActiveMessage).

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 vượt qua MessageListener để xử lý việc nhận thư đã đăng ký.

Bạn có thể gọi SubscribeOptions.setStrategy() (không bắt buộc) để đặt chiến lược để sử dụng.

Ví dụ sau 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 MessageListener được dùng để đăng ký (trong ví dụ này là mMessageListener).

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

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