Working with Beacons
Beacons are represented as
Beacon objects in IBM MobileFirst Platform Foundation. Beacons are identified by universally unique identifiers (UUID), major and minor values. The UUID in its canonical form is represented by 32 lowercase hexadecimal digits. The major and minor values are positive numbers in the range of 0-65535 (inclusive).
Beacon objects also contain a
customData field which is a JSON payload that specified customer-specific data representing the beacon; for example, the store or location where the beacon is deployed.
You can register, update, and delete beacons by using REST APIs. For detailed information about REST APIs, see the Reference part of the user documentation.
The following topics are covered:
- Registering beacons
- Registering beacon triggers
- Associating beacons and beacon triggers
- Using the server-side API to retrieve beacons and triggers
- Client-side API
Register the following beacons by using the beacons (PUT) REST API.
Registering beacon triggers
Beacon triggers are represented as
BeaconTrigger objects in IBM MobileFirst Platform Foundation. Beacon triggers are identified by the following parameters:
dwellingTime (optional), and
triggerTypeparameter determines when the trigger is activated, depending on the device location.
Trigger Type Description Enter The trigger is activated when the device enters the associated beacon region. Exit The trigger is activated when the device leaves the associated beacon region. DwellInside The trigger is activated when the device remains inside the associated beacon region for a given time period. DwellOutside The trigger is activated when the device remains outside the associated beacon region for a given time period.
- The value of the
proximityStateparameter indicates when the trigger is activated, depending on the distance between the device and the beacon region. The default value is
Proximity State Description Immediate Physically very close Near Approximately 1 to 3 meters Far Beyond that distance
dwellingTimeparameter applies only to the trigger types
DwellOutsideand is mandatory for those types. It is specified in milliseconds and defines how long the device must be inside or outside a beacon region before the
dwellOutsidetrigger is activated.
actionPayloadparameter represents the details of the action to be taken when the trigger is activated.
You can register, update, or delete beacon triggers by using REST APIs. For detailed information about the REST APIs, see the Reference part of the user documentation.
Register the following beacon triggers by using the beacon trigger REST API (POST).
Associating beacons and beacon triggers
An association between a beacon and a beacon trigger is represented as a
BeaconTriggerAssociationobject in IBM MobileFirst Platform Foundation. You create, update, or delete associations by using REST APIs. For detailed information about REST APIs, see the Reference part of the user documentation.
To create associations between beacons and triggers for an application, use the Associate beacons and triggers (PUT) REST API:
Using the server-side API to retrieve beacons and triggers
You can retrieve beacons, triggers, and their associations by using the
applicationName– The name of the MobileFirst application
beaconsOfInterest– A JSON block or an array of JSON blocks identifying the beacons whose trigger associations have to be fetched.
To learn about the client-side API, select your environment
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.