Get Started with Beacons

This guide explains the steps required to start using Bluetooth low energy (BLE) beacons to provide proximity-based experiences for your users.

Obtain and configure beacons

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

1. Get some beacons
2. Configure your beacons
3. Register your beacons with Google
4. Add an attachment

1. Get some beacons

Visit our partners to get Eddystone supported beacon hardware:

Devices with supported hardware can be configured to advertise BLE just like a beacon. For example, Android devices supporting API Level 21 (Lollipop) or greater can use the BluetoothLeAdvertiser class to advertise BLE.

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.

Nearby Notifications and Physical Web on Chrome require HTTPS URLs.

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:

1. Launch the app and select the Google Developer project you want to use.
2. Position your device near the beacon. You should see a list of beacons.
3. 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. Use the Python sample scripts in the GitHub repository to make working with the API from the command line easier.

4. Add an attachment

These are the options for associating attachments with beacons (choose one):

1. Use the Google Beacon Dashboard (recommended).
2. Use the Proximity Beacon API

The Beacon Tools app does not currently support adding Nearby Notifications attachments.

Use the Google Beacon 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:

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

To add a Nearby Notification attachment:

1. Click View beacon details and select Nearby Notifications.
2. Enter a Title and two-letter language code.
3. Select either Production mode or Debug mode.
4. Click Web URL and choose the type of URL to add (Web URL, App intent, or Free-form App Intent).
5. Fill in the corresponding fields for the selected URL type.
6. (Optional) Add targeting rules to limit visibility based on device context.
7. Click Create to add the attachment.

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.

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.

The Python sample scripts make adding attachments from the command line much easier.

You can also add attachments by hand 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.