Publicar y suscribirse

Nearby Messages es una API de publicación y suscripción que permite que los dispositivos cercanos intercambien cargas útiles pequeñas de datos. Una vez que un dispositivo publica un mensaje, los dispositivos cercanos pueden recibirlo. En esta guía, se explican todas las funciones 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 por el intercambio de tokens pequeños a través de Bluetooth. Cuando un dispositivo detecta un token de otro 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 el descubrimiento de dispositivos y si los medios 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 en medios, y para controlar si se debe transmitir o analizar, debes pasar parámetros adicionales cuando creas publicaciones y suscripciones.

Cuando se publican y suscriben de forma activa, se muestra una notificación de "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 brinda 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.
  • Forzar la detención de una app que usa Nearby
  • Navega a la pantalla Configuración cercana.

Puedes usar PublishCallback() y SubscribeCallback() para detectar los casos en los que un usuario fuerza la detención del uso de Nearby en la app. Cuando esto sucede, se activa el método onExpired().

Dado que las APIs de Nearby Messages pueden afectar la duración de la batería, solo se deben usar desde una actividad en primer plano (con la excepción de BLE background subscribe).

Llama a publish() o subscribe() para usar la API de Nearby Messages. Tu app siempre debe ser simétrica en 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 del mensaje. Recomendamos que los mensajes tengan menos de 3 KB, ya que estos 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);
}

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 los mensajes

Para suscribirte a los 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 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 cancelar la suscripción y dejar de recibir mensajes del dispositivo, llama al 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);
}