Better physical stories with Google’s Nearby APIs (Part 1 of 3)
As part of Google Play Services, Google offers the Nearby APIs to developers who want to augment the experience of their end-users by incorporating physical proximity into their stories. The Nearby APIs sit on a number of different technologies, such as Bluetooth and Wi-Fi. However, you don’t need to understand any of these technologies to reap all their benefits. The Nearby APIs abstract away all of these details, leaving you with a plug-and-play interface that allows you to focus on your app’s business logic.
Nearby focuses on developer journeys that require physical proximity. The API categorizes these physical communications into three buckets:
- One-way message detection
- Two-way communications
- Device-pairing with Fast Pair
We’ll teach you how to use each of these options and their benefits.
We’ll begin with message detection, demonstrating how to and why you might integrate the Nearby Messages API into your app. Then we will walk you through a few scenarios in which the two-way communication features of the Nearby Connections API might benefit your app. And finally we will explain device-pairing with Fast Pair and its benefits for your end users.
Because Nearby is a Google Play Services API, it’s only available on Android devices with the Google Play Store.
Take back your physical space with Nearby Messages
Part 1 of Nearby series
Mobile technology has enabled us to redefine distance by removing it from the user experience. Messaging apps, like Gmail and Meet, and productivity apps, like Docs and Sheets, have enabled people to chat, get together, and collaborate in real time, regardless of their physical location on the globe — or off of it.
There are moments when making technology aware of physical proximity can make our experiences more magical. Here are just a few examples:
- A group of friends are alerted of each other’s close presence and can enjoy an impromptu lunch together at the mall’s food court
- A power shopper is alerted of a 15% discount as they walk into their favorite department store as a thank you for their business.
- A local news app combines local media to capture different perspectives and collaborate in real time.
Taking these critical user journeys into account, the Nearby Messages API allows interested users of your app to detect each other when they are in close physical proximity — whether the user is on Android or iOS. The API handles requesting the user facing permissions for you: The API checks the app’s permissions and requests the permissions from the user, who can then grant the required permissions. In order for the API to work, the user publishing the message must grant the app Bluetooth permission and the user who wishes to receive the message must grant the app both Bluetooth and Location permissions (Note that beginning in Android S subscribers no longer need to grant Location permission to receive the broadcasts).
The API defines close-proximity to be about a 100-meter radius, but allows for circles of about 5 feet.
To use the Nearby API in your project, include the following Gradle dependency (always use the latest version):
The Nearby Messages API works by grouping devices as Publishers or Subscribers:
- A Publisher is a device that sends out a broadcast message announcing its presence to whoever might be interested.
- A Subscriber is a device that has expressed interest in certain publications.
For example, all my friends and I are avid users of ExampleApp. I use ExampleApp to broadcast my lunch location to any of my friends that are nearby and have expressed interest in listening to my messages.
ExampleApp will allow my friends’ devices to detect the broadcast coming from my device, so while the broadcast itself is indiscriminate, ExampleApp is responsible for making it useful by only alerting my friends of my activity.
To gain a greater appreciation for how the API achieves its ends, let’s take a peek at how these transactions actually happen. Imagine three devices, where device X is a publisher and devices Y and Z are subscribers. All three devices are using ExampleApp.
- Device X publishes a message (such as “Hello World”).
- ExampleApp on device X uploads the message to Google’s Nearby server and in response receives a random UUID (such as “Hello World” => 123).
- Device X starts a BLE advertisement, advertising that UUID until the publishing stops.
- Devices Y and Z detect the BLE advertisement.
- Using Wi-Fi, devices Y and Z upload the UUID to the Nearby server.
- Google’s Nearby server then returns the raw message if the UUID and the app’s signatures match exactly. (The Nearby API provides the app “signature” so don’t worry about that part.)
- ExampleApp can now use the knowledge that X is near Y and Z in any number of creative ways.
Figure 1: Nearby Message flow
Your users do not need to have Google accounts in order to use the Nearby Messages API. However, because your app will be using the Google Nearby servers, you need a Google account for registering your app with us.
Once you have created a Google account, you have to go through the typical process of obtaining API keys through the Google Developer Console:
- Go to https://console.cloud.google.com/apis/credentials
- Click on “+ Create Credentials” and choose “API Key”
- Copy the API key created and paste it into your Android project’s manifest file
Developers can now publish a message using Nearby.getMessagesClient(this).publish(mMessage), where message represents the Message you want to broadcast.
If you are a Subscriber you don’t need a Message, just a callback for receiving the Messages.
The same app can be both a Publisher and a Subscriber. For example, if both my friend and I are looking to discover each other for lunch at the mall, then it’s very likely that we are both broadcasting our intention to have lunch while at the same time listening for each other.
It’s very important to stop publishing and subscribing as soon as the user leaves the feature in your app that prompted them to use nearby so as to save battery and protect user privacy.
To stop publishing, call:
To stop subscribing, call:
Best Practices
We don’t recommend sending messages back and forth using the Nearby server (even though it’s possible).
First, the “Hello World” message is not encrypted and you shouldn’t publish sensitive information through the Nearby Server. Instead, once you verify close physical proximity through the Nearby APIs, you can transition to something like Firebase Cloud Messaging (FCM) to continue the communication.
Second, the battery life can be impacted if you continually use the Nearby server as a messaging service.
The Nearby Messages API can run in foreground mode or in background mode. In background mode, there is little battery cost as the API only scans for a few seconds when you turn your screen on. However, in foreground mode, the API will scan all the time, meaning that if the screen is off and Nearby Messages discovers a beacon, it ends up waking up the application processor and those wake-ups are quite costly — often up to 2.5X to 3.5X the normal battery consumption rate.
Therefore, instead of relying on Nearby Messages for continuous communication, as noted above, you should transition to a service like Firebase Cloud Messaging (FCM) once you have established proximity with Nearby Messages.
Summary
The Nearby Messages API is perfect for one-way communication among devices. It allows devices to broadcast messages to interested parties, and the API is available and works across both Android and iOS.
For more information on how to leverage the Nearby Messages API, visit our documentation and samples. Stay tuned for part 2 in this series, where we will cover the Nearby Connections API.
Check out more in Part 2 of this blog series, here.
