Nearby Messages es una API de publicación y suscripción que permite que los dispositivos cercanos intercambien pequeñas cargas útiles de datos. Una vez que un dispositivo publica un mensaje, los dispositivos cercanos pueden recibirlo. En esta guía, se explica toda la funcionalidad que debe implementar tu app para publicar mensajes y suscribirse a ellos con la API de Nearby Messages.
El conjunto de dispositivos cercanos se determina mediante el intercambio de tokens pequeños a través de Bluetooth. Cuando un dispositivo detecta un token de un dispositivo cercano, lo envía al servidor de Nearby Messages para validarlo y verificar si hay mensajes para entregar al conjunto actual de suscripciones de la aplicación.
Una aplicación puede controlar el conjunto de medios que se usan para la detección de dispositivos y si los medios se usan para transmitir tokens o para analizarlos. De forma predeterminada, la transmisión y el análisis se realizan en todos los medios. Para realizar la detección en un subconjunto o medios, y para controlar si se transmite o se analiza, debes pasar parámetros adicionales cuando creas publicaciones y suscripciones.
Cuando se publica y se suscribe de forma activa, se muestra una notificación "Nearby está en uso" que informa a los usuarios que Nearby está activo. Esta notificación solo se muestra cuando una o más apps usan Nearby de forma activa, lo que les da a los usuarios la oportunidad de conservar la duración de la batería si no se necesita Nearby. Proporciona a los usuarios las siguientes opciones:
- Navegar a una app para inhabilitar Nearby
- Forzar una app para que deje de usar Nearby
- Navegar a la pantalla Configuración de Nearby
Puedes usar PublishCallback()
y SubscribeCallback()
para detectar casos en los que un usuario obliga a la app a dejar de usar Nearby. Cuando esto
sucede, se
onExpired()
activa el método.
Debido a que las APIs de Nearby Messages pueden afectar la duración de la batería, solo deben usarse desde una actividad en primer plano (con la excepción de la suscripción en segundo plano de BLE).
Llama a publish()
o subscribe()
para usar la API de Nearby Messages. Tu app siempre debe
de forma simétrica unpublish()
y unsubscribe()
en 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();
}
Publicar un mensaje
Para publicar un mensaje, llama a Nearby.getMessagesClient(Activity).publish()
y pasa tu array de bytes de mensaje. Te recomendamos que los mensajes tengan menos de 3 KB (estos mensajes se pueden entregar más rápido), pero podemos admitir hasta 100 KB para las apps que lo necesiten. Este servicio no está diseñado para intercambiar objetos más grandes, como fotos y videos.
De forma opcional, puedes llamar a PublishOptions.setStrategy()
para establecer la estrategia
que se usará.
En el siguiente ejemplo, se muestra cómo llamar a publish() para enviar un mensaje de texto corto:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Anular la publicación de un mensaje
Para anular la publicación de un mensaje, llama a unpublish(). Como mínimo, tu
app debe llamar a unpublish en su onStop()
método. Pasa el mismo Message
objeto que se usó para publicar (mActiveMessage en este ejemplo).
En el siguiente ejemplo de código, se muestra cómo llamar a unpublish():
private void unpublish() {
Log.i(TAG, "Unpublishing.");
if (mActiveMessage != null) {
Nearby.getMessagesClient(this).unpublish(mActiveMessage);
mActiveMessage = null;
}
}
Suscribirse a mensajes
Para suscribirte a mensajes de otros dispositivos, llama a Nearby.getMessagesClient(Activity).subscribe(). Deberás pasar
un MessageListener
para controlar la recepción de mensajes suscritos.
De forma opcional, puedes llamar a SubscribeOptions.setStrategy()
para establecer la estrategia
que se usará.
En el siguiente ejemplo, se muestra cómo suscribirse a mensajes:
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);
}
Anular la suscripción
Para anular la suscripción y dejar de recibir mensajes del dispositivo, llama a
Nearby.getMessagesClient(Activity).unsubscribe(). Pasa el mismo
MessageListener
objeto que se usó para suscribirse (mMessageListener en este ejemplo).
En el siguiente ejemplo de código, se muestra cómo anular la suscripción:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}