Geofences and Beacons on iOS

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 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:

• Your account must have the Responsys Events Interface feature enabled, which is a Controlled Availability feature. To request access to this feature, please contact your Customer Success Manager or log in to My Oracle Support and create a service request.

• Your organization's mobile apps must be built with the 19A Responsys Push SDK (version 6.40.0) or greater, when it becomes available.

• Your organization's mobile apps must also be integrated with your chosen solution for geofencing, or beacons, or both. Depending on your solution, integration may also involve setup by a Responsys user with access to the Responsys Events Interface.

Responsys-side configuration and use

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

• Geofence and Beacon event variables

• Responsys Event Interface

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.

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).

• Objective-C
• Swift

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)

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).

• Objective-C
• Swift

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)

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).

• Objective-C
• Swift

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
	}
})

Beacon Entry Event Object Attributes - (PIOBeaconRegion)

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).

• Objective-C
• Swift

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
	}
})

Beacon Exit Event Object Attributes - (PIOBeaconRegion)

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.