Get Started with Nearby Notifications

Nearby Notifications is an upcoming new feature for contextual device, app, and website discovery. Nearby Notifications reveals what you can do with what's around you by automatically scanning for beacons and other devices, and surfacing the associated data to your app. This functionality is built in to Google Play Services, so you don't need to add anything to your app to start using it.

There are three basic types of experience that you can provide using Nearby Notifications:

Advertise an HTTPS URL to provide a notification to the user, and open the URL in the browser when the user taps the notification. This option does not require an app.
Trigger an app intent to launch an app that is already installed and perform a specific action. If the app isn't installed, the user is redirected to a mobile web page of the developer's choosing (specify a web fallback URL).
Trigger an app install to launch an app and perform a specific action. If the app is not installed, the user is taken to the Play Store where the app is installed; the user can then continue to the feature specified by the developer (a fallback URL is not required). URLs of this type require explicit whitelisting from Google. Apply for the App Install Program.

Obtain and configure beacons

To get beacons and set them up, take the following steps:

Get some beacons
Configure your beacons
Register your beacons with Google
Add an attachment

1. Get some beacons

Visit our partners to get Eddystone supported beacon hardware:

2. Configure your beacons

Before a beacon can be used, you must provision it to set the frame type, broadcast intervals and power levels. Currently you must use the software that was provided by your beacon manufacturer to do this.

To advertise a data or URL attachment, you can use either Eddystone-UID, or Eddystone-EID frame types. To advertise a URL, use the Eddystone-URL frame type.

With Eddystone-UID and Eddystone-EID, you can:

Associate one or more data or URL attachments with a beacon.
Remotely update beacon attachments.
Monitor beacons using the Google Beacon Dashboard.

Eddystone-EID also lets you control who can access your beacons; only services that share an encryption key with an Eddystone-EID beacon can resolve message data from that beacon. For more information, see Eddystone Ephemeral Identifier.

Eddystone-URL lets you advertise a URL (HTTP or HTTPS), and is designed for interacting with the Physical Web. Nearby Notifications can also show HTTPS URLs broadcast from Eddystone-URL devices, although Eddystone-URL does not support app intent or app install URLs. We recommend using a URL redirector to enable the use of longer URLs, and to make it possible to update the URL after the beacon is deployed. When using this frame type, you cannot register the beacon with Google. Once you have provisioned the beacon, no further steps are required.

If you provisioned your beacons using Eddystone-UID or Eddystone-EID, continue to the next step. If you provisioned your beacons using Eddystone-URL, you're done!

3. Register your beacons with Google

Next, register ownership of your beacons with the Google Beacon Registry. To do this, use the Beacon Tools app, available for Android and iOS.

To register the beacon:

Launch the app and select the Google Developer project you want to use.
Position your device near the beacon. You should see a list of beacons.
Select the beacon you want to register, then tap Register Beacon. The beacon should then appear under the Registered tab.

You can also use the Proximity Beacon API to register beacons.

4. Add an attachment

There are three options for associating attachments with beacons (choose one):

Use the Google Beacon Dashboard (recommended).
Use the Beacon Tools app.
Use the Proximity Beacon API

Option 1: Use the Beacons Dashboard

The Google Beacon Dashboard is the easiest way to associate attachments with your beacons.

Follow these steps to add an attachment using the Google Beacon Dashboard:

Go to the Google Beacon Dashboard.
Select your project from the list of Google Developers Console projects.
Select your beacon from the list.
Enter details for your beacon in the provided form.

To add a Nearby Notification attachment:

Click View beacon details and select Nearby Notifications.
Enter a Title, Description, and two-letter language code.
Select either Production mode or Debug mode.
Click Web URL and choose the type of URL to add (Web URL, App intent with web URL fallback, or App intent with install fallback).
Fill in the corresponding fields for the selected URL type.
Click Create to add the notification.

Note that you can add multiple attachments to a beacon. For more information about how to format attachments and URLs for Nearby Notifications, see Attachment Data Format.

Option 2: Use the Beacon Tools app

To create a notification that is only visible to phones in developer mode, for example during development or testing, append the -debug flag to the namespace type field. For example a type of en-debug means the notification will only be shown on phones set to the English language that are in developer mode. In this case, the `namespacedType` would look like this: `com.google.nearby/en-debug`. Additionally, with -debug, no approval is required to show app install notifications.

You can use the Beacon Tools app to associate attachments with beacons by following these steps:

Install the Beacon Tools app (Android, iOS).
Launch the app. You'll see a list of beacons near you. If your beacon has been registered with Google, it will appear under the Registered tab. If not, you'll need to register your beacon.
Tap your beacon to select it.
To add a new attachment, click the plus sign (+) next to Attachments, and enter the attachment data.
Under Namespaced Type enter en-debug where en is the two-letter language code. Omit -debug when you're ready to move your attachment into production. Currently the namespace value is fixed to the Google Developers Console project that the beacon was registered under. The ability to edit the namespace is coming soon.

Under Data enter an attachment. For example:

{
  "title": "Google",
  "description": "Search for things!",
  "url": "https://www.google.com"
}

Tap the checkmark icon to save your changes.

For more information about how to format attachments and URLs for Nearby Notifications, see Attachment Data Format.

Option 3: Use the Proximity Beacon API

You can also use the Proximity Beacon API to associate attachments with beacons. Note that this will require you to base64 encode your request body.

Upload an attachment by making a POST request to:

  https://proximitybeacon.googleapis.com/v1beta1/beacons/BEACON_NAME/attachments

where BEACON_NAME is a string of the form:

3!EDDYSTONE_UID

and the request body includes the namespaced type and base64 encoded data as shown in the following example:

{
  "namespacedType":"com.google.nearby/en",
  "data":"ew0KICAidGl0bGUiOiAiR29vZ2xlIiwNCiAgImRlc2NyaXB0aW9uIjogIlNlYXJjaCBmb3IgdGhpbmdzISIsDQogICJ1cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlLmNvbSINCn0="
}

If the request succeeds, you'll receive a 200 OK status code, and the attachment body.

For more information about how to format attachments and URLs for Nearby Notifications, see Attachment Data Format.