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

[1.] Record a Geofence Entry event

App developers can use the SDK API onGeoRegionEntered to record any Geofence Entry event as and when it occurs in the application context. The API takes in two arguments, a PIOGeoRegion object and a completion listener PIORegionCompletionListener. In the PIOGeoRegion, the parameters geofenceId and geofenceName are the mandatory fields. Also any Strings in the object should have a length less than 256 characters.

The completion listener, PIORegionCompletionListener, helps in identifying if a error occurred while sending the events to the server. The error can be found from the PIORegionException in the onRegionReported().

PushIOManager.getInstance(getContext()).onGeoRegionEntered
                (geoRegion, new PIORegionCompletionListener() {
                    @Override
                    public void onRegionReported(String s, PIORegionEventType pioRegionEventType, PIORegionException e) {

                    }
                });

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. Android 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
deviceSpeed 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
deviceBearing 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 Map<String, String> 256 characters Custom parameters to pass with Geofence information. Maximum 5 parameters are allowed. area : Jones Street, category : apparel Optional

[2.] Record a Geofence Exit event

Similarly, to record any Geofence Exit events at the server, the app developers can use the onGeoRegionExited() API.

PushIOManager.getInstance(getContext()).onGeoRegionExited
                (geoRegion, new PIORegionCompletionListener() {
                    @Override
                    public void onRegionReported(String s, PIORegionEventType pioRegionEventType, PIORegionException e) {

                    }
                });

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. Android 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 Map<String, String> 256 characters Custom parameters to pass with Geofence information. Maximum 5 parameters are allowed. area : Jones Street, category : apparel Optional

[3.] Record a Beacon Entry event

The SDK also has support for beacon related entry or exit events. For recording Beacon Entry event, app developers need to use onBeaconRegionEntered() API. The API takes in two parameters, a PIOBeaconRegion object and a completion listener object similar to the one used in [1.] and [2.] In the PIOBeaconRegion, the beaconId and beaconName are the mandatory fields, and any String values should be of length less than 256 characters

PushIOManager.getInstance(getContext()).onBeaconRegionEntered
                (beaconRegion, new PIORegionCompletionListener() {
                    @Override
                    public void onRegionReported(String s, PIORegionEventType pioRegionEventType, PIORegionException e) {

                    }
                });

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. Android 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 String NA Major value of iBeacon 1 Optional
iBeaconMinor String 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 Map<String, String> 256 characters Custom parameters to pass with Beacon information. Maximum 5 parameters are allowed. area : Jones Street, category : apparel Optional

[4.] Record a Beacon Exit event

Similarly, a Beacon Exit event can be recorded using the onBeaconRegionExited() API.

PushIOManager.getInstance(getContext()).onBeaconRegionExited
                (beaconRegion, new PIORegionCompletionListener() {
                    @Override
                    public void onRegionReported(String s, PIORegionEventType pioRegionEventType, PIORegionException e) {

                    }
                });

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. Android 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 beacon is not iBeacon use this for any other id purpose if required like eddystoneurl. ffffffff-1234-aaaa-1a2b-a1b2c3d4e5f6 Optional
iBeaconMajor String NA Major value of iBeacon 1 Optional
iBeaconMinor String 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 Map<String, String> 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.