Working with Beacons

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
• Registering beacon triggers
• Associating beacons and beacon triggers
• Using the server-side API to retrieve beacons and triggers
• Client-side API

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

• Beacons in Android
• Beacons in iOS