Work with geofences and triggers

We can use geofences and triggers to identify users who enter, exit, or stay inside or outside a geographical area. We can initiate actions, such as improving responsiveness for privileged guests at a hotel chain, based on geofence-related data.

Acquisition of geolocation data must be started before we can receive triggers related to geofences. See Set an acquisition policy.

A geofence is a geographical area, which is defined in the form of a circle or polygon. We can increase or decrease the size of the area by changing the value of the bufferZoneWidth parameter in the WL.Device.startAcquisition method.

Triggers are used to identify users who enter, exit, or stay inside or outside a geofence. For the entering and exiting triggers, the user must have been previously outside or inside the area, including the buffer zone, for the trigger to occur.

Confidence levels are used to help determine whether the trigger condition is met. We can also use them to trade off sensitivity, correctness, and battery usage. A confidence level of low, which is the default, uses the acquired position and does not take into account the accuracy of the measurement. The medium and high confidence levels do take accuracy into account. The medium confidence level indicates that the system is approximately 70% confident that the condition is met. The high confidence level corresponds to a level of approximately 95%.

A low confidence level indicates that the condition is met more often, although there is a higher likelihood of it being mistaken. A high confidence level indicates that the condition is met less often, however it is less likely to be mistaken.

After an Enter trigger is activated, it will not activate again until the user leaves the "activated" area, which includes the buffer zone. For the entering and dwelling-inside triggers, this means that the user must exit the area. For the exiting and dwelling outside triggers, this means that the user must enter the area.

1. Start acquiring geolocation data, using the WL.Device.startAcquisition method.

2. Include trigger definitions for geofence triggers: Enter, Exit, DwellInside, and DwellOutside.

3. Set confidence levels for the triggers.

4. Set events to be transmitted when triggers are activated.

Example

For hybrid Android, iOS, or Windows Phone 8

function wlCommonInit(){
 /*
  * Use of WL.Client.connect() API before any connectivity to a MobileFirst Server is required. 
  * This API should be called only once, before any other WL.Client methods that communicate with the MobileFirst Server.
  * Don't forget to specify and implement onSuccess and onFailure callback functions for WL.Client.connect(), e.g:
  *    
  *    WL.Client.connect({
  *      onSuccess: onConnectSuccess,   *      onFailure: onConnectFailure
  *    });
  *     
  */
 
 // Common initialization code goes here  WL.App.hideSplashScreen();
 
}  
  
  // Common initialization code goes here }
var triggers = {
  Geo: {
    centralPark: {
      type: "DwellInside",   polygon: [
        {longitude: -73.95824432373092, latitude: 40.80062106285157},     {longitude: -73.94948959350631, latitude: 40.79691751000037},     {longitude: -73.97309303283704, latitude: 40.764486356929645},     {longitude: -73.98167610168441, latitude: 40.76799670467469}
      ],   dwellingTime: 600000, // 10 minutes
      bufferZoneWidth: -100, // at least 100 meters within the park
      callback: after10MinsInCentralPark
    }, statueOfLiberty: {
      type: "Enter",   circle: {
        longitude: -74.044444,     latitude: 40.689167,     radius: 5000 // 5km
      },   confidenceLevel: "high", // ~95% confidence that you are in the circle
      eventToTransmit: {
        event: {
          nearAttraction: "statue_of_liberty"
        },     transmitImmediately: true
    }
};

For native Android

WLTriggersConfiguration triggers = new WLTriggersConfiguration();
triggers.getGeoTriggers().put("centralPark",    new WLGeoDwellInsideTrigger()
     .setArea(new WLPolygon(Arrays.asList(
            new WLCoordinate(40.80062106285157, -73.95824432373092),         new WLCoordinate(40.79691751000037, -73.94948959350631),         new WLCoordinate(40.764486356929645, -73.97309303283704),         new WLCoordinate(40.76799670467469, -73.98167610168441))))
     .setDwellingTime(600000) // 10 minutes
     .setBufferZoneWidth(-100) // at least 100 meters within the park
     .setCallback(after10MinsInCentralPark));
triggers.getGeoTriggers().put("statueOfLiberty",    new WLGeoEnterTrigger()
     .setArea(new WLCircle(new WLCoordinate(40.689167, -74.044444), 5000)) // 5 km
     .setConfidenceLevel(WLConfidenceLevel.HIGH) // ˜95% confidence that we are in the circle
     .setEvent(new JSONObject("{nearAttraction: 'statue_of_liberty'}"))
     .setTransmitImmediately(true));

For native iOS

WLTriggersConfiguration* triggers = [[WLTriggersConfiguration alloc] init];
[[triggers getGeoTriggers] setObject:
   [[[[
      [[WLGeoDwellInsideTrigger alloc] init]
         setArea: [[WLPolygon alloc] init: [NSMutableArray arrayWithObjects:
                  [[WLCoordinate alloc] initWithLatitude:40.80062106285157 longitude:-73.95824432373092],               [[WLCoordinate alloc] initWithLatitude:40.79691751000037 longitude:-73.94948959350631],               [[WLCoordinate alloc] initWithLatitude:40.764486356929645 longitude:-73.97309303283704],               [[WLCoordinate alloc] initWithLatitude:40.76799670467469 longitude:-73.98167610168441],               nil]]]
         setDwellingTime: 60000] // 10 minutes
         setBufferZoneWidth: -100] // at least 100 meters within the park
         setCallback: after10MinsInCentralPark]    
   forKey:@"centralPark"];
  
  
[[triggers getGeoTriggers] setObject:
   [[[[
      [[WLGeoEnterTrigger alloc] init]
         setArea: [[WLCircle alloc] initWithCenter:[[WLCoordinate alloc] initWithLatitude:40.689167 longitude:-74.044444] radius:5000]]
         setConfidenceLevel: HIGH] // ˜95% confidence that we are in the circle
         setEvent: [NSDictionary dictionaryWithObject: @"statue_of_liberty" forKey:@"nearAttraction"]]
         setTransmitImmediately: true]
   forKey:@"statueOfLiberty"];

Parent topic: Location services