Overview

Skill Level: Intermediate

Watson Campaign Automation 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¬† Watson Campaign Automation. 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.

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

Location Universal Behavior events are available in  Watson Campaign Automation 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.

Go Back to the Mobile App Messaging home page.

Join The Discussion

Your email address will not be published. Required fields are marked *