Mensajes cercanos 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 tu app debe implementar 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 Mensajes cercanos 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 estos se usan para transmitir tokens o buscar tokens. De forma predeterminada, la transmisión y el análisis 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 se publica y se suscribe de forma activa, se presenta una notificación que indica que Nearby está en uso para informar 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 que use Nearby.
- Navega a la pantalla Configuración de Nearby.
Puedes usar PublishCallback() y SubscribeCallback() para detectar los casos en los que un usuario fuerza a la app a dejar de usar Nearby. Cuando esto
sucede, se activa el método
onExpired().
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 llamar de forma simétrica a 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 el array de bytes del mensaje. Te recomendamos que mantengas los mensajes en 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 manera 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
breve:
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 llamar a la anulación de la publicación en su método onStop(). Pasa el mismo objeto Message 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 los 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 manera opcional, puedes llamar a SubscribeOptions.setStrategy() para establecer la estrategia que se usará.
En el siguiente ejemplo, se muestra cómo suscribirse a los 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 suscribirse (mMessageListener en este ejemplo).
En el siguiente ejemplo de código, se muestra cómo cancelar la suscripción:
private void unsubscribe() {
Log.i(TAG, "Unsubscribing.");
Nearby.getMessagesClient(this).unsubscribe(mMessageListener);
}