Working with Beacons

improve this page | report issue

Overview

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

Register the following beacons by using the beacons (PUT) REST API.

{
    "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
    "major": 1,
    "minor": 4417,
    "customData": {
        "branchName": "Indiranagar, Bangalore"
    }
}

{
    "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
    "major": 2,
    "minor": 4417,
    "customData": {
        "branchName": "Koramangala, Bangalore"
    }
}

Registering beacon triggers

Beacon triggers are represented as BeaconTrigger objects in IBM MobileFirst Platform Foundation. Beacon triggers are identified by the following parameters: triggerName, triggerType, proximityState, dwellingTime (optional), and actionPayload.

  • The triggerType parameter 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 proximityState parameter indicates when the trigger is activated, depending on the distance between the device and the beacon region. The default value is Far.
    Proximity State Description
    Immediate Physically very close
    Near Approximately 1 to 3 meters
    Far Beyond that distance


  • The dwellingTime parameter applies only to the trigger types DwellInside and DwellOutside and 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 dwellInside or dwellOutside trigger is activated.
  • The actionPayload parameter 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).

    {
        "triggerName": "entryIntoBranch",
        "triggerType": "Enter",
        "proximityState": "Near",
        "actionPayload": {
            "alert": "Welcome to $branchName branch of IMF Bank"
        }
     }


    {
        "triggerName": "entryIntoLoanSection",
        "triggerType": "Enter",
        "proximityState": "Immediate",
        "actionPayload": {
            "alert": "Welcome to the Loan processing section. You will be assisted soon by our staff."
        }
    }


    {
        "triggerName": "exitFromBranch",
        "triggerType": "Exit",
        "proximityState": "Far",
        "actionPayload": {
            "alert": "Thank you for visiting our $branchName branch. Have a nice day!"
        }
    }

    Associating beacons and beacon triggers

    An association between a beacon and a beacon trigger is represented as a BeaconTriggerAssociation object 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:

    {
        "beacons": [
            {
                "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
                "major": 1,
                "minor": 4417
            },
            {
                "uuid": "3d402cf0-3691-4bd9-97ff-0b0a93a160ef",
                "major": 2,
                "minor": 4417
            }
        ],
        "triggers": [
            {
                "triggerName": "entryIntoBranch",
                "triggerName": "exitFromBranch",
                "triggerName": "entryIntoLoanSection"
            }
        ]
    }

    Using the server-side API to retrieve beacons and triggers

    You can retrieve beacons, triggers, and their associations by using the
    WL.Server.getBeaconsAndTriggers(applicationName, beaconsOfInterest) API.

    • 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

Last modified on November 09, 2016