发布和订阅

Nearby Messages 是一种发布/订阅 API，可让附近的设备交换少量数据。设备发布消息后，附近的设备便可以接收该消息。本指南将引导您完成应用必须实现的所有功能，以便使用 Nearby Messages API 发布消息和订阅消息。

附近的设备集由通过蓝牙交换的小令牌决定。当设备检测到来自附近的设备的令牌时，会将该令牌发送到 Nearby Messages 服务器进行验证，并检查是否有任何消息要传递给应用的当前订阅集。

应用可以控制用于设备发现的媒介集，以及这些媒介是用于广播令牌和/或扫描令牌。默认情况下，广播和扫描会在所有媒介上完成。如需在部分媒介上进行发现，以及控制是广播还是扫描，您必须在创建发布和订阅时传递其他参数。

在主动发布和订阅时，系统会显示“附近正在使用中”通知，告知用户“附近”功能处于活跃状态。只有在一个或多个应用正在使用“附近”功能时，系统才会显示此通知，以便用户在不需要“附近”功能时节省电池电量。它为用户提供以下选项：

• 前往应用以停用“附近”功能。
• 强制应用停止使用“附近”功能。
• 前往附近设置界面。

您可以使用 PublishCallback() 和 SubscribeCallback() 监听用户强制应用停止使用 Nearby 的情况。发生这种情况时，系统会触发 onExpired() 方法。

由于 Nearby Messages API 可能会影响电池续航时间，因此只能从前台 activity 中使用（BLE 后台订阅除外）。

调用 publish() 和/或 subscribe() 以使用 Nearby Messages API。您的应用应始终在 onStop() 中对称地unpublish()和unsubscribe()。

@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();
}

发布消息

如需发布消息，请调用 Nearby.getMessagesClient(Activity).publish() 并传递消息字节数组。我们建议将消息大小控制在 3KB 以下，以便我们更快地传递这些消息，但对于有需要的应用，我们最多可支持 100KB。此服务不适用于交换照片和视频等较大的对象。

您可以选择调用 PublishOptions.setStrategy() 来设置要使用的策略。

以下示例演示了如何调用 publish() 来发送简短短信：

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.getMessagesClient(this).publish(mActiveMessage);
}

注意： 此示例未设置发布状态的回调。如需设置回调，请在发布时传递 PublishOptions 以及有效的 PublishCallback。您还应在发布调用末尾附加一个 OnFailureListener，以便在发布失败时收到通知。例如，如果设备未连接到互联网。

取消发布消息

如需取消发布消息，请调用 unpublish()。您的应用至少应在其 onStop() 方法中调用取消发布。传递用于发布的同一 Message 对象（在本例中为 mActiveMessage）。

以下代码示例展示了如何调用 unpublish()：

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

订阅消息

如需订阅来自其他设备的消息，请调用 Nearby.getMessagesClient(Activity).subscribe()。您需要传递 MessageListener 来处理接收订阅的消息。

您可以选择调用 SubscribeOptions.setStrategy() 来设置要使用的策略。

以下示例演示了如何订阅消息：

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);
}

注意： 与发布一样，您可以为订阅状态设置回调。订阅时，请传递具有有效 SubscribeCallback 的 SubscribeOptions。您还应在订阅调用结束时附加 OnFailureListener，以便在订阅失败时收到通知。例如，如果设备未连接到互联网。

退订

如需退订并停止接收设备消息，请调用 Nearby.getMessagesClient(Activity).unsubscribe()。传递用于订阅的同一 MessageListener 对象（在本例中为 mMessageListener）。

以下代码示例演示了如何退订：

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