Nearby Messages es una API de publicación y suscripción que permite que los dispositivos cercanos intercambien pequeñas cargas útiles de datos. Cuando un dispositivo publica un mensaje, los dispositivos cercanos pueden recibirlo. En esta guía, se explican todas las funcionalidades 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 por 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 que entregar para el conjunto actual de suscripciones de la aplicación.
Una aplicación puede controlar el conjunto de medios que se usan para el descubrimiento de dispositivos y si los medios se usan para transmitir tokens o buscar tokens. De forma predeterminada, la transmisión y la búsqueda se realizan en todos los medios. Para realizar el descubrimiento en un subconjunto o medios y controlar si se debe transmitir o analizar, debes pasar parámetros adicionales cuando creas publicaciones y suscripciones.
Cuando publicas y te suscribes de forma activa, se muestra una notificación que indica que Nearby está en uso, lo que les 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:
- Navega a una app para inhabilitar Nearby.
- Fuerza la detención de una app para que deje de usar Nearby.
- Navega a la pantalla de Configuración de Nearby.
Puedes usar PublishCallback() y SubscribeCallback() para detectar casos en los que un usuario fuerza a la app a dejar de usar Nearby. Cuando esto sucede, se activa el método onExpired().
Como las APIs de Nearby Messages tienen el potencial de afectar la duración de batería, solo deben usarse desde una actividad en primer plano (a 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 unpublish() y unsubscribe() de manera simétrica 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 el array de bytes del mensaje. Recomendamos que los mensajes tengan menos de 3 KB (estos mensajes se pueden enviar 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 manera opcional, puedes llamar a PublishOptions.setStrategy() para configurar la estrategia que se usará.
En el siguiente ejemplo, se muestra cómo llamar a publish() para enviar un pequeño mensaje de texto:
private void publish(String message) {
Log.i(TAG, "Publishing message: " + message);
mActiveMessage = new Message(message.getBytes());
Nearby.getMessagesClient(this).publish(mActiveMessage);
}
Cómo anular la publicación de un mensaje
Para anular la publicación de un mensaje, llama a unpublish(). Como mínimo, tu app debe solicitar la anulación de la publicación en su método onStop(). Pasa el mismo objeto Message que se usó para publicar el contenido (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;
}
}
Cómo suscribirse a mensajes
Para suscribirte a mensajes de otros dispositivos, llama a Nearby.getMessagesClient(Activity).subscribe(). Deberás pasar un MessageListener para administrar la recepción de mensajes de usuarios suscritos.
De manera opcional, puedes llamar a SubscribeOptions.setStrategy() para configurar la estrategia que se usará.
En el siguiente ejemplo, se muestra la suscripción 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 objeto MessageListener que se usó para la suscripción (mMessageListener en este ejemplo).
En el siguiente ejemplo de código, se muestra la anulación de suscripciones:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}