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. The steps you must take here depend on the way you plan to use your beacons.

Ways to use beacons

Most of the use cases for beacons fall under one of the following categories:

Receiving Nearby Messages and Notifications

You can add attachments to your beacons, and access those attachments as messages, with your own app using Nearby Messages and Nearby Notifications, which does not require your app to be installed. Since the messages are stored in the cloud, you can update them as often as you like without the need to update the beacons themselves.

Interacting with the Physical Web

The Physical Web enables quick, seamless interaction with beacons. If you want your beacon to link to a single web page, you can broadcast Eddystone-URL frames. This compressed URL can be read by Nearby Notifications, and by Chrome using the Physical Web. Note that beacons configured using Eddystone-URL can't be registered with Google's beacon registry.

Integrating with Google services

When your beacons are registered with Google, the Places API uses fields such as latitude and longitude coordinates, indoor floor level, and Google Places PlaceID as signals to improve location detection accuracy automatically.

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:

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:

  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 Beacon Tools app.
  3. Use the Proximity Beacon API

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 an attachment:

  1. Click the down-arrow next to View beacon details and select attachments.
  2. Enter the Type, and Value for the attachment. The value for Namespace is fixed, depending on the Google Developers Console project that you selected.
  3. Click the plus sign (+) to add the attachment.
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.
  8. 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 Beacon Tools app

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

  1. Install the Beacon Tools app (Android, iOS).
  2. 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.
  3. Tap your beacon in the list to select it.
  4. To add a new attachment, click the plus sign (+) next to Attachments, and enter the attachment data.
  5. Under Namespaced Type enter a two-letter language code. 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.
  6. Under Data enter an attachment. For example:

    Beacon edd1ebeac04e5defa023 at your service!
    
  7. Tap the checkmark icon to save your changes.

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

Developer Guidelines

As you build proximity-based experiences for your users, you might collect and manage user information through your apps. For example, some of the information that you collect may allow you to infer a user's location or activity. Your users trust you to do the right thing with their data. It's your responsibility to do so, but keep these key principles in mind:

  • Comply with all relevant privacy laws and regulations when handling user information.
  • Provide users with (and follow) a privacy policy explaining what user information you collect and how you use it.
  • Honor user requests to delete their data.
  • Carefully review the Terms of Service before using the Proximity Beacon API, and other terms of service which may apply to your use of other Google APIs, for example the Nearby Messages API.

Next steps