Add Attachments to Beacons

You can associate arbitrary data with a beacon using an attachment. Attachments are stored as blobs in Google’s scalable cloud. You can retrieve existing attachments via an API request, for example as messages using the Nearby Messages API.

Once a beacon has been registered it is ready to accept attachments. The Proximity Beacon API and beacon dashboard make it easy to manage attachments on registered beacons. A single beacon can support multiple attachments so that you can associate different attachment data for different use cases.

You can authorize people to manage your attachments, or share your beacons with other developers so that they can add their own attachments for use in their apps using Proximity Beacon API's IAM roles.

Attachment content

When you create an attachment, you must populate two fields:

  • namespacedType: a string made up of a namespace identifier, followed by a forward slash and the attachment type. For example, surreptitious-banjo-145/string.
  • data: a base64 encoded value of the data type defined in the namespacedType field. For example, aGVsbG8gd29ybGQh.

To find out which namespaces are associated with your project, call namespaces.list. Note that the namespace of an attachment in the beacon registry is independent of the Eddystone-UID namespace.

Attachment type is an arbitrary string that you can use to separate different categories of attachments. The Nearby Messages API allows you to control which types of beacon attachment a particular client is subscribed to, ensuring that your app is only woken when an interesting beacon is close by.

Attachments can be up to 1024 bytes long. You can use any string that has meaning to your app, for example the ID for a bus stop or store location, structured data such as JSON, or a reference to an external datastore. Consider linking to external data when:

  • You want to return large data items such as pictures and videos.
  • Your data resides on a third-party database that you do not control.
  • You want to return confidential or sensitive data that should not be stored in beacon attachments.
  • You run a proprietary authentication system that relies on your own database.

Some Google products, such as Nearby Notifications, use attachment data to provide their service. In these cases, the attachment namespace is specified by the service (for example, com.google.nearby), and attachment data should follow that service's specified schema.

Attachment visibility

Attachment visibility controls which projects can access attachment data for a particular namespace, using either the beaconinfo.getforobserved method or the Nearby Messages API. You can set the visibility for a namespace to PUBLIC so that any calling project can retrieve data for attachments created in that namespace, or UNLISTED, in which case the calling project must own the namespace in order to retrieve attachment data. The calling project is identified by API key.

By default, your project's namespace visibility is set to UNLISTED, so its attachments are served only to your project, not to other developers' projects.

If you wish other developers to be able to make use of attachment data in your namespace then you can set the namespace visibility to PUBLIC using the namespaces.update method. Updating the visibility affects all attachments with that namespace.

A single beacon can support multiple attachments in different namespaces, added by different projects using the Proximity Beacon API's IAM roles. Each project controls the visibility of its namespace, so it is possible for a single beacon to support a mixture of public and unlisted attachments.

Example: Add an attachment to a beacon

This example demonstrates how to attach data (the string aGVsbG8gd29ybGQh) to a beacon.

HTTP method

POST

Request URL

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

Request body
 {
  "namespacedType":"surreptitious-banjo-145/my-attachment-type",
  "data":"aGVsbG8gd29ybGQh"
}

Response

If the attachment is created successfully, the response is a 200 OK status code. The response body contains a JSON representation of the attachment, including a BeaconAttachment.attachment_name property that can be used as the reference to manage the attachment.