Nearby Messages API

Recently I gave a talk on Beacons at the GDG Johannesburg. I received a few questions about how the Nearby Messages API works and how developers can integrate it into their app. To address these questions, I decided to go into some more detail and provide an example of how this API works.

The Nearby Messages API , What is it?

‘The Nearby Messages API is a publish-subscribe API that lets you pass small binary payloads between internet-connected Android and iOS devices.’

What does this mean to us as developers? Well, this is an API where we can either use our mobile devices may it be Android or iOS devices and be able to broadcast small messages to other Bluetooth devices that are listening. We can then also use this API to listen for not only Nearby messages from mobile devices but also from other Bluetooth devices , such as Beacons, that might be transmitting messages to a specific app on our phones.

How does it work?

Nearby messages can be implemented on both Android and iOS. The example I’ll be showing is in Android.

This API has some requirements before we dive right into writing code. Since we are using an API that requires the user’s phone to have their location on, we need to ask for permission for our application to use this. In Android you would set this in the application’s manifest.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Now to jump into some code. Firstly we need to set up a GoogleAPIClient:

private synchronized void buildGoogleApiClient()
 {   
    if (mGoogleApiClient == null) 
    {      
      mGoogleApiClient = new GoogleApiClient.Builder(this)    
                .addApi(Nearby.MESSAGES_API, new  MessagesOptions.Builder()                         .setPermissions(NearbyPermissions.BLE).build()) 
               .addConnectionCallbacks(this)    
                .enableAutoManage(this, this)     
               .build();
    }
}

Once the Google API Client is set up, we can now use the Nearby Messages API to publish messages to other devices and subscribe to them.

To publish a message it’s just two simple lines of code.

private void publish(String message) 
{        
    Message mActiveMessage = new Message(message.getBytes());
    Nearby.Messages.publish(mGoogleApiClient, mActiveMessage);  
}

You are now publishing messages out to the world!

So how do we receive these messages? Well, that’s where subscribing comes along. When subscribing using the Nearby messages API, there are a few things that you need to do in preparation.

Firstly, you need an IntentService to scan for published messages even when your app is in the background.

Within this IntentService, you will need to be able to handle messages once the Nearby Messages API has found a message. This is done in the onHandleIntent method. In this method, you need to call the Nearby.Messages.handleIntent method and register a MessageListener. This listener gives you a message when it finds one or once it’s not within the range of that message anymore.

public class NearbyBackgroundService extends IntentService 
{     
     public NearbyBackgroundService(String name) 
     {      
          super(name);   
     }    
     @Override    protected void onHandleIntent(Intent intent) 
     {
        if (intent != null) 
        {
            Nearby.Messages.handleIntent(intent, new   MessageListener() 
{
                @Override public void onFound(Message message) 
                {
                   Log.i("", "found message = " + message);                
                }              
               @Override public void onLost(Message message)
                { 
                  Log.i("", "lost message = " + message);                   
                }            
        });       
      }  
    }
}

Now that we have a Service to listen for our messages we can now subscribe and get these messages.

To do this, we use the subscribe function from the messages API and we add a pendingIntent which is our ServiceIntent. We then subscribe to listen for messages. We can also add a Result Callback to make sure that we have successfully subscribed.

Nearby.Messages.subscribe(mGoogleApiClient, getPendingIntent(), options)

When we don’t want to listen for messages anymore, we can just unsubscribe and we will no longer be listening for messages.

Nearby.Messages.unsubscribe(mGoogleApiClient, getPendingIntent());

This is the basics of the Nearby Messages API. Once we have done this exchange of messages from one phone to another, we can then look at getting messages from devices such as Beacons. Using the above code, we can subscribe to beacon messages that use the Google Beacon Platform and Eddystone Format.

I’ll cover this in my next post, so stay tuned!.

For more information about the Nearby Messages API you can visit the Google Developers website:

Overview | Nearby Messages API | Google Developers

Discover nearby devices, then send and receive data.developers.google.com

For a more complete example of the above code, you can visit my Github page:

pjwelcome/GDGBeacons

Get in touch!

Peter-John (@pjapplez) | Twitter

Peter John Welcome — Google+

Thanks to Ashton Welcome and Joshua Leibstein for reviewing this post.