Configuring location plug-ins for beacon and geofence integration with apps developed in Cordova

Overview

Prerequisites

Step-by-step

1. 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/com.xtify.mce.sdk.location 
   --variable SYNC_RADIUS=10000 --variable SYNC_INTERVAL=60 
   cordova prepare 

2. 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/com.xtify.mce.sdk.geofence
   cordova prepare 

3. 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/com.xtify.mce.sdk.beacon 
   --variable UUID=8EE07E37-8EE5-4CF4-8A98-992D08285CF0
   cordova prepare 

    

   Note: Support for iBeacons was added in the 17.1 release and support for Zebra beacons was added in the 17.2 release. Other beacons are not supported. 

4. 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 
   });

    

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

    

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