Nearby Messages 是一种发布-订阅 API,可让附近的设备交换少量载荷。设备发布消息后,附近的设备可以接收该消息。本指南介绍了您的应用为了使用 Nearby Messages API 发布消息和订阅消息而必须实现的所有功能。
附近的设备集通过通过蓝牙交换小令牌来确定。当设备从附近的设备检测到令牌时,会将该令牌发送到“附近消息”服务器以验证该令牌,并检查对于应用的当前订阅集,是否有任何消息要传送。
应用可以控制用于设备发现的媒介集,以及这些媒介是否用于广播令牌和/或扫描令牌。默认情况下,系统会在所有媒介上执行广播和扫描操作。如需在子集上执行发现操作,并控制是广播还是扫描,您必须在创建发布内容和订阅时传递其他参数。
在主动发布和订阅时,系统会显示“‘附近’功能正在使用中”通知,告知用户“附近”功能已启用。仅当一个或多个应用正在使用“附近”功能时,系统才会显示此通知,这样一来,在不需要“附近”功能时,用户有机会延长电池续航时间。它可为用户提供以下选项:
- 前往某个应用以停用“附近”功能。
- 强制应用停止使用“附近”功能。
- 前往附近设置屏幕。
您可以使用 PublishCallback()
和 SubscribeCallback()
监听用户强制应用停止使用“附近”功能的情况。在这种情况下,系统会触发 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);
}
取消发布消息
如需取消发布消息,请调用 unpublish()
。您的应用至少应在其 onStop()
方法中调用 unpublish。传递用于发布的同一 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);
}
退订
如需退订并停止接收设备消息,请调用 Nearby.getMessagesClient(Activity).unsubscribe()
。传递用于订阅的同一 MessageListener
对象(本例中为 mMessageListener
)。
以下代码示例演示了如何退订:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}