Beacons

Beacons detects nearby Bluetooth beacons. Beacons are like hardware-enabled micro-geofences, accurate down to a few meters. For example, you might create a store-level geofence and monitor beacons installed at the entrance, in the drive-thru, on registers, on tables, in aisles, or in parking spaces at each store.

Beacons provides the following user context:

{
  beacons: [
    {
      uuid: "B9407F30-F5F8-466E-AFF9-25556B57FE6D",
      majorId: "100",
      minorId: "1",
      description: "Store #123 - Register #1",
      tag: "store-register",
      externalId: "1",
      enabled: true
    },
    {
      uuid: "C9407F30-F5F8-466E-AFF9-25556B57FE6D",
      majorId: "100",
      minorId: "2",
      description: "Store #123 - Register #2",
      tag: "store-register",
      externalId: "123-2",
      enabled: true
    }
  ]
}

Beacons also provides the following events:

  • user.entered_beacon
  • user.exited_beacon

You can receive events client-side via the SDK or server-side via event integrations, including webhooks.

Beacons is available on the Team plan and higher.

How it works

Beacon detection works on iOS and Android in the foreground and in the background. After you import beacons, Radar will sync nearby beacons to the SDK on every location update. Radar can range any beacons compatible with iBeacon.

Just like the Radar generates user.entered_geofence events after you import geofences, Radar will generate user.entered_beacon events after you import beacons.

To range beacons, the user must grant location permissions. If the user grants foreground location permissions, you can range nearby beacons in the foreground by calling Radar.trackOnce(desiredAccuracy, beacons, completionHandler:) with beacons = true. If the user grants background location permissions, you can monitor beacons in the background by calling Radar.startTracking() with trackingOptions.beacons = true. See the SDK reference for more information.

Beacon entry and exit events are sent to the SDK, to webhooks, and to integrations just like geofence entry and exit events.

CSV import

Like geofences, you also specify the metadata for beacons when you create them, including tag (an optional group for the geofence, e.g., store-register), external ID (an optional external ID for the beacon that maps to your internal database, e.g., 123-1), description (a display name for the beacon, e.g., Store #123 - Register #1).

You also specify the identifiers used to range the beacon, including uuid, majorId, and minorId, as well as an approximate latitude and longitude used to sync nearby beacons (within 1 kilometer) to the SDK.

Beacons should be uniquely referenced by tag and external ID, assigned by you when a beacon is created. To disable or rotate identifiers for a beacon, re-import the beacon with the same tag and external ID.

To import beacons, go to the Beacons page and click the Import button. Then, select a CSV to upload.

The CSV must have 8 columns:

  • description (required): A display name for the beacon.
  • tag (optional, but recommended): A group for the beacon.
  • externalId (optional, but recommended): An external ID for the beacon that maps to your internal database.
  • type (required): The type of beacon. ibeacon is currently supported.
  • uuid (required): The UUID of the beacon.
  • majorId (required): The major ID of the beacon.
  • minorId (required): The minor ID of the beacon.
  • coordinates (required): The approximate location of the beacon, used to sync nearby beacons (within 1 kilometer) to the SDK. A JSON string in the format [longitude,latitude]. Note that longitude comes before latitude, a GeoJSON convention.
  • enabled (required): If true, the beacon will generate events. If false, the beacon will not generate events.
  • metadata (required): A set of custom key-value pairs for the beacon. A JSON string representing a dictionary with up to 16 keys and values of type string, boolean, or number.

Headers for the columns should be omitted. In other words, the first row of the CSV should correspond to the first geofence.

If a beacon with the specified tag and external ID already exists, it will be updated. If not, it will be created.

For example, to import beacons installed on registers and in parking spaces at a store, you could use the following CSV:

"Store #123 - Register #1",store-register,123-1,ibeacon,"B9407F30-F5F8-466E-AFF9-25556B57FE6D",100,1,"[-73.975363,40.783826]",true,{}
"Store #123 - Register #2",store-register,123-2,ibeacon,"C9407F30-F5F8-466E-AFF9-25556B57FE6D",100,1,"[-73.975363,40.783826]",true,{}
"Store #123 - Parking Space #1",store-parking,123-1,ibeacon,"D9407F30-F5F8-466E-AFF9-25556B57FE6D",101,1,"[-73.975363,40.783826]",true,{}
"Store #123 - Parking Space #2",store-parking,123-2,ibeacon,"E9407F30-F5F8-466E-AFF9-25556B57FE6D",101,2,"[-73.975363,40.783826]",true,{}