Publicar y suscribirse

Mensajes de Nearby es una API de publicación y suscripción que permite que los dispositivos cercanos intercambien cargas útiles de datos pequeñas. 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 algún mensaje para entregar al 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 se usan para transmitir tokens o buscarlos. 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 crees publicaciones y suscripciones.

Cuando se publican y se suscriben servicios de manera activa, se muestra una notificación que indica que Nearby está en uso y 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 brinda a los usuarios la oportunidad de ahorrar batería si no es necesario usar Nearby. Proporciona a los usuarios las siguientes opciones:

• Navega a una app para inhabilitar Nearby.
• Fuerza a una app a dejar de usar Nearby.
• Navega 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 activa el método onExpired().

Debido a que las APIs de Nearby Messages pueden afectar la duración de 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 unpublish() y unsubscribe() de forma 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 sean de menos de 3 KB, ya que podemos entregarlos 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 configurar 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);
}

Nota: En este ejemplo, no se establecieron devoluciones de llamada para el estado de la publicación. Para configurar una devolución de llamada, pasa PublishOptions con un PublishCallback válido cuando publiques. También debes adjuntar un OnFailureListener al final de la llamada de publicación, que te notificará si la publicación falló. Por ejemplo, si el dispositivo no tiene una conexión a Internet activa.

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

Cómo suscribirse a mensajes

Para suscribirte a mensajes desde otros dispositivos, llama a Nearby.getMessagesClient(Activity).subscribe(). Deberás pasar un MessageListener para controlar la recepción de mensajes de suscripción.

De forma opcional, puedes llamar a SubscribeOptions.setStrategy() para configurar 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);
}

Nota: Al igual que con la publicación, puedes establecer una devolución de llamada para el estado de la suscripción. Pasa SubscribeOptions con un SubscribeCallback válido cuando te suscribas. También debes adjuntar un OnFailureListener al final de la llamada de suscripción, que te notificará si la suscripción falló. Por ejemplo, si el dispositivo no tiene una conexión a Internet activa.

Anular la suscripción

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