Publish and Subscribe

Nearby Messages is a publish-subscribe API which lets nearby devices exchange small payloads of data. Once a device publishes a message, nearby devices can receive the message. This guide walks you through all of the functionality your app must implement in order to publish messages, and subscribe to messages using the Nearby Messages API.

The set of nearby devices is determined by the exchange of small tokens over Bluetooth and ultrasonic (inaudible) audio. When a device detects a token from a nearby device, it sends the token to the Nearby Messages server to validate it and check if there are any messages to deliver for the application’s current set of subscriptions.

An application can control the set of mediums used for device discovery, and whether the mediums are used to broadcast tokens and/or scan for tokens. By default, broadcasting and scanning is done on all the mediums. To do discovery on a subset or mediums, and to control whether to broadcast or scan, you must pass additional parameters when you create publications and subscriptions.

When actively publishing and subscribing, a "Nearby is in use" notification is presented, informing users that Nearby is active. This notification is only displayed when one or more apps are actively using Nearby, giving users a chance to conserve battery life if Nearby is not needed. It provides users with the following options:

  • Navigate to an app to disable Nearby.
  • Force an app to stop using Nearby.
  • Navigate to the Nearby Settings screen.

You can use PublishCallback() and SubscribeCallback() to listen for cases when a user forces the app to stop using Nearby. When this happens, the onExpired() method is triggered.

Because the Nearby Messages APIs have the potential to impact battery life, they should only be used from a foreground activity (with the exception of BLE background subscribe).

You will only be able to publish() or subscribe() after the GoogleApiClient has connected. Therefore, it's best to do so either in onConnected() or in response to a user action. Your app should always symetrically unpublish() or unsubscribe() in onStop().

public void onCreate(Bundle savedInstanceState) {
    mGoogleApiClient = new GoogleApiClient.Builder(this)
            .enableAutoManage(this, this)

public void onConnected(Bundle connectionHint) {
    publish("Hello World");

public void onStop() {

Anatomy of a request

When making a request to publish a message, or to subscribe to messages from nearby devices, your app should do the following:

  1. Ensure that the Google API Client is connected.
  2. Call the appropriate method (publish(), subscribe(), unpublish(), unsubscribe()) In the case of subscriptions, also use a MessageListener to handle any messages that are received when subscribing.
  3. Upon ending the activity, stop all publish and subscribe tasks in onStop().

Publish a message

To publish a message, call Nearby.Messages.publish() passing your message byte array. We recommend keeping the messages to less then 3KB--these messages we can deliver faster--but we can support up to 100KB for apps that need it. This service is not meant for exchanging larger objects such as photos and videos.

You can optionally call PublishOptions.setStrategy() to set the strategy to use.

The following example demonstrates calling publish() to send a small text message:

private void publish(String message) {
    Log.i(TAG, "Publishing message: " + message);
    mActiveMessage = new Message(message.getBytes());
    Nearby.Messages.publish(mGoogleApiClient, mActiveMessage);

Unpublish a message

To unpublish a message, call unpublish(). At minimum your app should call unpublish in its onStop() method. Pass the same Message object that was used to publish (mActiveMessage in this example).

The following code example shows calling unpublish():

private void unpublish() {
    Log.i(TAG, "Unpublishing.");
    if (mActiveMessage != null) {
        Nearby.Messages.unpublish(mGoogleApiClient, mActiveMessage);
        mActiveMessage = null;

Subscribe to messages

To subscribe to messages from other devices, call Nearby.Messages.subscribe(). You'll need to pass a MessageListener to handle receiving subscribed messages.

You can optionally call SubscribeOptions.setStrategy() to set the strategy to use.

The following example demonstrates subscribing to messages:

public void onCreate(Bundle savedInstanceState) {
    mMessageListener = new MessageListener() {
        public void onFound(Message message) {
            String messageAsString = new String(message.getContent());
            Log.d(TAG, "Found message: " + messageAsString);

        public void onLost(Message message) {
            String messageAsString = new String(message.getContent());
            Log.d(TAG, "Lost sight of message: " + messageAsString);

// Subscribe to receive messages.
private void subscribe() {
    Log.i(TAG, "Subscribing.");
    Nearby.Messages.subscribe(mGoogleApiClient, mMessageListener, options);


To unsubscribe and stop receiving device messages, call Nearby.Messages.unsubscribe(). Pass the same MessageListener object that was used to subscribe (mMessageListener in this example).

The following code example demonstrates unsubscribing:

private void unsubscribe() {
    Log.i(TAG, "Unsubscribing.");
    Nearby.Messages.unsubscribe(mGoogleApiClient, mMessageListener);

Enviar comentarios sobre…

Nearby Messages API for Android
Nearby Messages API for Android