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. 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).

Call publish() and/or subscribe() to use the Nearby Messages API. Your app should always symetrically unpublish() and unsubscribe() in 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();
}

Publish a message

To publish a message, call Nearby.getMessagesClient(Activity).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.getMessagesClient(this).publish(mActiveMessage);
}

Note: This example has not set callbacks for the publish's status. To set a callback, pass PublishOptions with a valid PublishCallback when publishing. You should also append a OnFailureListener to the end of the publish call, which will notify you if the publish has failed. For instance, if the device doesn't have an active internet connection.

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.getMessagesClient(this).unpublish(mActiveMessage);
        mActiveMessage = null;
    }
}

Subscribe to messages

To subscribe to messages from other devices, call Nearby.getMessagesClient(Activity).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) {
    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);
}

Note: Just like publishing, you're able to set a callback for the status of the subscription. Pass SubscribeOptions with a valid SubscribeCallback when subscribing. You should also append a OnFailureListener to the end of the subscribe call, which will notify you if the subscribe has failed. For instance, if the device doesn't have an active internet connection.

Unsubscribe

To unsubscribe and stop receiving device messages, call Nearby.getMessagesClient(Activity).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.getMessagesClient(this).unsubscribe(mMessageListener);
}