Oracle Help Center | Oracle Responsys Mobile App Platform Cloud Service title

Geofences and beacons

This topic provides steps for configuring your mobile app to handle location-based triggers using geofences and beacons.

 

About location-based marketing using geofences and beacons

Responsys now supports geofence and beacon events. The Responsys Push SDK has added a set of open APIs that enable app developers to raise entry and exit events for geofences and beacons. You can integrate with a geofence/beacon solution of your choice, or integrate with a native geofence/beacon solution.

Once implemented, marketers will be able to use geofence and beacon events in their program orchestrations in Responsys. These location-based events will be triggered when a mobile device user enters or exits a geofence or beacon zone.

To enable this feature:

Responsys-side configuration and use

See the following topics in the Responsys Help Center for more information:

 

Steps to integrate the location-based triggers for geofences and beacons

The iOS SDK provides API to raise the Geofence and Beacon events. You need to raise these events when users enter or exit predefined geofence or beacon regions. You can call these APIs from iOS Location Services delegate methods or any other third party SDK's you are using to capture these events.

[1.] Triggering a Geofence Entry event

To trigger a Geofence Entry event you can use didEnterGeoRegion API and call it when your app gets notified for geofence region entry. This API takes two arguments, a PIOGeoRegion object and a completion handler. In the PIOGeoRegion, the parameters geofenceId and geofenceName are mandatory fields. You can provide any additional details to capture the event more accurately. Also any Strings in the object should not have more than 256 characters.

The API returns response or error (if errors occur while sending the event to the Responsys server).

PIOGeoRegion *geoRegion = [[PIOGeoRegion alloc] initWithGeofenceId:@"123" geofenceName:@"FENCE_1" speed:2.0 bearing:5.0 source:@"Apple Native" zoneId:@"123" zoneName:@"NY Wall Street" dwellTime:0 extra:@{@"area":@"Empire State Building", @"category":@"Food"}];
[[PushIOManager sharedInstance] didEnterGeoRegion:geoRegion completionHandler:^(NSError *error, NSString *response) {
    if (nil == error) {
        //Geofence Entry Event triggered successfully
    } else {
        NSLog(@"Unable to send Geofence Entry Event, reason: %@", error.description);
    }
}];
        
let geoRegion: PIOGeoRegion = PIOGeoRegion(geofenceId: "123", geofenceName: "FENCE_1", speed: 2.0, bearing:5.0, source: "Apple Native", zoneId:"123", zoneName:"NY Wall Street" , dwellTime: 0, extra: ["area":"Empire State Building", "category":"Food"])
PushIOManager.sharedInstance().didEnter(region: geoRegion, { (error, response) in
    if let error = error {
        print("Unable to send Geofence Entry Event, reason: \(error.debugDescription)")
    } else {
        //Geofence Entry Event triggered successfully
    }
})
        

Geofence Entry Event Object Attributes - (PIOGeoRegion)

Property Data Type Max Length Description Example Required/Optional
source String 256 characters The source of the event. App developers can choose to use this attribute to include details like the name of the Geofence and Beacon SDK/solution that they have integrated with, or the name of the Beacon hardware. Apple Native Optional
zoneId String 256 characters ID of the region / zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. 123 Optional
zoneName String 256 characters Name of the Region / Zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. NY Wall Street Optional
geofenceId String 256 characters ID for the Geofence 123 Required
geofenceName String 256 characters Name of the Geofence FENCE_1 Required
speed double NA Speed of the device when the Geofence transition was triggered. Units depend on the Geofence SDK / solution being used by the app. 40 Optional
bearing double NA Bearing / Direction of travel for the device when the Geofence transition was triggered. Bearing is usually the horizontal direction of travel and is measured in degrees. 2 Optional
extra NSDictionary 256 characters Custom parameters to pass with Geofence information. Maximum 5 parameters are allowed. @{@"area":@"Empire State Building", @"category":@"Food"} Optional

[2.] Triggering a Geofence Exit event

Similarly, to trigger Geofence Exit event, you can use the didExitGeoRegion API and call it when your app gets notified of a geofence region exit. This API takes two arguments, a PIOGeoRegion object and a completion handler. In the PIOGeoRegion, the parameters geofenceId and geofenceName are mandatory fields. You can provide any additional details to capture the event more accurately. Also any Strings in the object should not have more than 256 characters.

The API returns response or error (if errors occur while sending the event to Responsys server).

PIOGeoRegion *geoRegion = [[PIOGeoRegion alloc] initWithGeofenceId:@"1" geofenceName:@"something" speed:0.0 bearing:0.0 source:@"bluecat" zoneId:@"zone" zoneName:@"ss" dwellTime:10 extra:@{@"area":@"Empire State Building", @"category":@"Food"}];
[[PushIOManager sharedInstance] didExitGeoRegion:geoRegion completionHandler:^(NSError *error, NSString *response) {
    if (nil == error) {
        //Geofence Exit Event triggered successfully
    } else {
        NSLog(@"Unable to send Geofence Exit Event, reason: %@", error.description);
    }
}];
        
let geoRegion: PIOGeoRegion = PIOGeoRegion(geofenceId: "123", geofenceName: "FENCE_1", speed: 0.0, bearing:0.0, source: "Apple Native", zoneId:"123", zoneName:"NY Wall Street" , dwellTime:10, extra: ["area":"Empire State Building", "category":"Food"])
PushIOManager.sharedInstance().didExit(region: geoRegion, { (error, response) in
    if let error = error {
        print("Unable to send Geofence Exit Event, reason: \(error.debugDescription)")
    } else {
        //Geofence Exit Event triggered successfully
    }
})
        

Geofence Exit Event Object Attributes - (PIOGeoRegion)

Property Data Type Max Length Description Example Required/Optional
source String 256 characters The source of the event. App developers can choose to use this attribute to include details like the name of the Geofence and Beacon SDK/solution that they have integrated with, or the name of the Beacon hardware. Apple Native Optional
zoneId String 256 characters ID of the region / zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. 123 Optional
zoneName String 256 characters Name of the Region / Zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. Jpnagar Optional
geofenceId String 256 characters ID for the Geofence 123 Required
geofenceName String 256 characters Name of the Geofence FENCE_1 Required
dwellTime Integer NA Time spent inside the Geofence (in minutes / seconds). The units of the Dwell Time depend on the solution being used by the app. 240 Optional
extra NSDictionary 256 characters Custom parameters to pass with Geofence information. Maximum 5 parameters are allowed. @{@"area":"Empire State Building", @"category":@"Food"} Optional

[3.] Triggering a Beacon Entry event

The SDK also supports beacon-related entry or exit events. To trigger Beacon Entry event, you can use the didEnterBeaconRegion API and call this event when your app gets notified for beacon region entry event. This API takes two arguments, a PIOBeaconRegion object and a completion handler. In the PIOBeaconRegion, the beaconId and beaconName are the mandatory fields. You can provide any additional details to capture the event more accurately. Also any Strings in the object should not have more than 256 characters.

The API returns response or error (if errors occur while sending the event to Responsys server).

NSString *proximityString;
switch(proximity) //CLProximity
{
    default:
    case CLProximityUnknown:   proximityString = @"Unknown";   break;
    case CLProximityImmediate: proximityString = @"Immediate"; break;
    case CLProximityNear:      proximityString = @"Near";      break;
    case CLProximityFar:       proximityString = @"Far";       break;
}

PIOBeaconRegion *beaconRegion = [[PIOBeaconRegion alloc] initWithiBeaconUUID:@"ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6" iBeaconMajor:1 iBeaconMinor:2 beaconId:@"123" beaconName:@"beacon-1" beaconTag:@"KR_Entry" proximity:proximityString source:@"Apple Native" zoneId:@"123" zoneName:@"NY Wall Street" dwellTime:0 extra:  @{@"area":"Empire State Building", @"category":@"apparel"}];
[[PushIOManager sharedInstance] didEnterBeaconRegion:beaconRegion completionHandler:^(NSError *error, NSString *response) {
    if (nil == error) {
        //Beacon Entry Event triggered successfully
    } else {
        NSLog(@"Unable to send Beacon Entry Event, reason: %@", error.description);
    }
}];
        
let beaconRegion: PIOBeaconRegion = PIOBeaconRegion(iBeaconUUID: "ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6", iBeaconMajor: 1, iBeaconMinor: 2, beaconId: "123", beaconName: "beacon-1", beaconTag: "KR_Entry", proximity: "Near", source: "Apple Native", zoneId: "123", zoneName: "NY Wall Street", dwellTime: 10, extra: ["area":"Empire State Building", "category":"Food"])
PushIOManager.sharedInstance().didEnter(region: beaconRegion, { (error, response) in
    if let error = error {
        print("Unable to send Beacon Entry Event, reason: \(error.debugDescription)")
    } else {
        //Beacon Entry Event triggered successfully
    }
})
        

Beacon Entry Event Object Attributes - (PIOBeaconRegion)

Property Data Type Max Length Description Example Required/Optional
source String 256 characters The source of the event. App developers can choose to use this attribute to include details like the name of the Geofence and Beacon SDK/solution that they have integrated with, or the name of the Beacon hardware. Apple Native Optional
zoneId String 256 characters ID of the region / zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. 123 Optional
zoneName String 256 characters Name of the Region / Zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. NY Wall Street Optional
beaconId String 256 characters ID for the Beacon 123 Required
beaconName String 256 characters Name of the Beacon beacon-1 Required
beaconTag String 256 characters Any tag to further categorize this Beacon. KR_Entry Optional
iBeaconUUID String 256 characters Proximity UUID of iBeacon. If beacon is not iBeacon use this for any other id purpose if required like eddystoneurl. ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6 Optional
iBeaconMajor Integer NA Major value of iBeacon 1 Optional
iBeaconMinor Integer NA Minor value of iBeacon. 2 Optional
eddyStoneId1 String 256 characters UUID of EddyStone Beacon. You can use this field for any other purpose in case beacon is not eddystone. ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6 Optional
eddyStoneId2 String 256 characters Instance ID of EddyStone Beacon. You can use this field for any other purpose in case beacon is not eddystone. 456 Optional
proximity String 256 characters User's / Device's proximity from the Beacon. Possible values are: Immediate, Near, Far, Unknown Near Optional
extra NSDictionary 256 characters Custom parameters to pass with Beacon information. Maximum 5 parameters are allowed. @{@"area":"Jones Street", @"category":@"apparel"} Optional

[4.] Triggering a Beacon Exit event

Similarly, to trigger Beacon Exit event, you can use the didExitBeaconRegion API and call this event when your app gets notified for beacon region exit event. This API takes two arguments, a PIOBeaconRegion object and a completion handler. In the PIOBeaconRegion, the beaconId and beaconName are the mandatory fields. You can provide any additional details to capture the event more accurately. Also any Strings in the object should not have more than 256 characters.

The API returns response or error (if errors occur while sending the event to Responsys server).

NSString *proximityString;
switch(proximity) //CLProximity
{
    default:
    case CLProximityUnknown:   proximityString = @"Unknown";   break;
    case CLProximityImmediate: proximityString = @"Immediate"; break;
    case CLProximityNear:      proximityString = @"Near";      break;
    case CLProximityFar:       proximityString = @"Far";       break;
}
        
PIOBeaconRegion *beaconRegion = [[PIOBeaconRegion alloc] initWithiBeaconUUID:@"ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6" iBeaconMajor:1 iBeaconMinor:2 beaconId:@"123" beaconName:@"beacon-1" beaconTag:@"KR_Entry" proximity:proximityString source:@"Apple Native" zoneId:@"123" zoneName:@"NY Wall Street" dwellTime:10 extra:  @{@"area":"Empire State Building", @"category":@"apparel"}];
[[PushIOManager sharedInstance] didExitBeaconRegion:beaconRegion completionHandler:^(NSError *error, NSString *response) {
    if (nil == error) {
        //Beacon Exit Event triggered successfully
    } else {
        NSLog(@"Unable to send Beacon Exit Event, reason: %@", error.description);
    }
}];
        
let beaconRegion: PIOBeaconRegion = PIOBeaconRegion(iBeaconUUID: "ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6", iBeaconMajor: 1, iBeaconMinor: 2, beaconId: "123", beaconName: "beacon-1", beaconTag: "KR_Entry", proximity: "Near", source: "Apple Native", zoneId: "123", zoneName: "NY Wall Street", dwellTime: 10, extra: ["area":"Empire State Building", "category":"Food"])
PushIOManager.sharedInstance().didExit(region: beaconRegion, { (error, response) in
    if let error = error {
        print("Unable to send Beacon Entry Event, reason: \(error.debugDescription)")
    } else {
        //Beacon Exit Event triggered successfully
    }
})
        

Beacon Exit Event Object Attributes - (PIOBeaconRegion)

Property Data Type Max Length Description Example Required/Optional
source String 256 characters The source of the event. App developers can choose to use this attribute to include details like the name of the Geofence and Beacon SDK/solution that they have integrated with, or the name of the Beacon hardware. Apple Native Optional
zoneId String 256 characters ID of the region / zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. 123 Optional
zoneName String 256 characters Name of the Region / Zone. A region or zone represents a logical boundary for a Region that a Marketer wants to monitor. Often in location based services products, Geofences and Beacons are included within Regions or Zones. NY Wall Street Optional
beaconId String 256 characters ID for the Beacon 123 Required
beaconName String 256 characters Name of the Beacon FENCE_1 Required
beaconTag String 256 characters Any tag to further categorize this Beacon. KR_Entry Optional
iBeaconUUID String 256 characters Proximity UUID of iBeacon. If the beacon is not iBeacon use this for any other id purpose if required like eddystoneurl. ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6 Optional
iBeaconMajor Integer NA Major value of iBeacon 1 Optional
iBeaconMinor Integer NA Minor value of iBeacon. 2 Optional
eddyStoneId1 String 256 characters UUID of EddyStone Beacon. You can use this field for any other purpose in case the Beacon is not eddystone. ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6 Optional
eddyStoneId2 String 256 characters Instance ID of EddyStone Beacon. You can use this field for any other purpose in case beacon is not eddystone. 456 Optional
proximity String 256 characters User's / Device's proximity from the Beacon. Possible values are: Immediate, Near, Far, Unknown Near Optional
extra NSDictionary 256 characters Custom parameters to pass with Beacon information. Maximum 5 parameters are allowed. @{@"area":"Jones Street", @"category":@"apparel"} Optional

Adding Optional Data

Developers can specify up to 5 additional key-value pairs in the extra property of the PIOGeoRegion and PIOBeaconRegion objects. This enables apps to implement a custom geofence and beacon solution for their mobile app. More than 5 custom attributes will result in an error.

NOTES:

  1. Any String fields for the geofence and beacon APIs should have a string length less than 256 characters.

  2. For PIOGeoRegion, mandatory fields are geofenceId and geofenceName. Whereas for the PIOBeaconRegion, mandatory fields are beaconId and beaconName.