Overview
Skill Level: Intermediate
Acoustic Campaign provides three location plug-ins that you can use to integrate beacons and geofences with iOS and Android apps developed in Cordova.
Prerequisites
- To integrate geofences, you require the Location Sync plug-in and the Geofence plug-in.
- To integrate beacons, you require the Location Sync plug-in and the Beacon plug-in.
- You use DLA to configure locations in Acoustic Campaign. For information about configuring DLA, see Device Location Awareness.
Â
About this task
When configuring locations, add the files for the appropriate plug-ins to your project and then register them. For example, to integrate beacons, add the files for the Location Sync plug-in and the Beacon plug-in.
Â
Not what you’re looking for? Check out all our available tutorials for mobile app messaging here.
Step-by-step
-
Add the Location Sync plug-in to Cordova projects
The Location Sync plug-in enables location syncing for both beacon and geofence regions. To use either beacons or geofences with apps developed in Cordova, you must first add the Location Sync plug-in to your project.
The Location Sync plug-in uses the following optional parameters for iOS and Android. If you do not include an optional variable in the command line, the default value is used.
SYNC_RADIUS
The radius of the reference area. Default is 100000 meters (100 km).
SYNC_INTERVAL
The time interval between reference area geofence and beacon synchronizations with the server. Default is 600 seconds (10 minutes). The minimum allowed value is 300 seconds. If you try to set the SYNC_INTERVAL to a value that is lower than 300 seconds, the SDK resets the value to 300 seconds.
Â
To add the Location Sync plug-in to your Cordova project, use the Cordova add command from the command line. For example:
cordova plugin add <path to downloaded directory>/plugins/co.acoustic.mobile.push.plugin.location
--variable SYNC_RADIUS=10000 --variable SYNC_INTERVAL=60
cordova prepare -
Add the Geofence plug-in to Cordova projects
The Geofence plug-in enables support for geofences in iOS and Android applications developed with Cordova. Before you add the Geofence plug-in to the project, ensure that you first add the Location Sync plug-in.
Â
To add the Geofence plug-in to your Cordova project, run the following command line:
cordova plugin add <path to downloaded directory>/plugins/co.acoustic.mobile.push.plugin.geofence
cordova prepare -
Add the Beacon plug-in to Cordova projects
The Beacon plug-in enables support for beacons in iOS and Android applications developed with Cordova. Before you add the Beacon plug-in to the project, ensure that you first add the Location Sync plug-in.
Â
UUID
UUID specifies the UUID for the beacons in your locations. The UUID is a randomly generated identifier that beacons emit and devices detect. Generally, an org uses only one UUID and the UUID is unique to the org. In DLA, beacons are identified by a hierarchical combination of a UUID, a major number, and a minor number, where UUID represents a group of associated beacons, such as the beacons associated with an organization.
Â
To add the Beacon plug-in to your Cordova project, run the following command line, where “8EE07E37-8EE5-4CF4-8A98-992D08285CF0” represents the UUID for your org:
cordova plugin add <path to downloaded directory>/plugins/co.acoustic.mobile.push.plugin.beacon
--variable UUID=8EE07E37-8EE5-4CF4-8A98-992D08285CF0
cordova prepareÂ
Â
-
Publish breach notifications for location events
If you want to be notified when geofence or beacon events occur, implement the following delegates:
Beacon entry:
MCEBeaconPlugin.setBeaconEnterCallback(function (beacon) {
// use beacon.major
// use beacon.minor
})Beacon exit:
MCEBeaconPlugin.setBeaconExitCallback(function (beacon) {
// use beacon.major
// use beacon.minor
})Geofence entry:
MCEGeofencePlugin.setGeofenceEnterCallback(function (geofence) {
// use geofence.latitude
// use geofence.longitude
// use geofence.radius
});Geofence exit:
MCEGeofencePlugin.setGeofenceExitCallback(function (geofence) {
// use geofence.latitude
// use geofence.longitude
// use geofence.radius
});Â -
Add the NSLocation key and string to the info.plist file
NSLocationAlwaysUsageDescription requests permission from the mobile app user to use location services when your app is running in the background. Because Apple recently started prohibiting apps from sharing location data with third parties when explicit user consent is absent, you might want to use NSLocationAlwaysUsageDescription to tell users how the SDK uses location data. The SDK stores location data locally on the device and when a geofence event is triggered, the event is sent to MCE, which a third party. The event does not contain raw location data. To convince users to grant permission, you might also want to let them know that battery usage is minimal when location sharing is enabled.
<key>NSLocationAlwaysUsageDescription</key>
<string>The SDK stores location data locally on the device and
when a geofence event is triggered, the event is sent to MCE,
which a third party. The event does not contain raw location data.
Battery usage is minimal when sharing location.</string>Note: You might also consider using the NSLocationWhenInUseUsageDescription key to allow location access only when the app is in use.
Â
iOS 11 (and later)
For iOS 11, you must add both the NSLocationWhenInUseUsageDescription key and the NSLocationAlwaysAndWhenInUseUsageDescription key to the Info.plist file.
<key>NSLocationAlwaysUsageDescription</key>
<string>The SDK stores location data locally on the device and
when a geofence event is triggered, the event is sent to MCE,
which a third party. The event does not contain raw location data.
Battery usage is minimal when sharing location.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>The SDK stores location data locally on the device and
when a geofence event is triggered, the event is sent to MCE,
which a third party. The event does not contain raw location data.
Battery usage is minimal when sharing location.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>The SDK stores location data locally on the device and
when a geofence event is triggered, the event is sent to MCE,
which a third party. The event does not contain raw location data.
Battery usage is minimal when sharing location.</string>Â
-
Start location services by calling the manualLocationInitialization method
If you installed the Cordova plug-in with the AUTO_INITIALIZE_LOCATION variable set to false, you start location services and monitoring for locations by calling the manualLocationInitialization method.
Expected outcome
Location Universal Behavior events are available in Acoustic Campaign queries and programs for iOS and Android apps that are developed in Cordova. For information about DLA, see DLA. For information about concepts and advanced features of the Cordova plug-in, see Documentation.
Â
Need more help? Check out all of our available tutorials for mobile app messaging here.