Overview

Skill Level: Intermediate

You can configure location support for geofences and beacons in the IBM Mobile App Messaging SDK for Android apps. When enabled for locations, the IBM Mobile App Messaging SDK contacts the Watson Campaign Automation server and requests a list of DLA-configured locations (geofences and beacons) that are within a specified distance of the user’s current location. The SDK registers the locations with the operating system on the user’s device and requests permission from the operating system to receive background location updates about the device’s location. The operating system updates the SDK with the user’s location at timed intervals, such as every 5 minutes. If the user moves away from the registered locations, the SDK registers a new list of locations that are based on the user’s new location. If the user breaches a geofence or beacon, the SDK triggers a location event.

Prerequisites

Before configuring the IBM Mobile App Messaging Android SDK  for geofence and beacon integration, configure locations in the Device Location Awareness (DLA) service. For more information, see Device Location Awareness.

About this task

To configure the IBM Mobile App Messaging SDK for locations, use the MCEConfig.json file to define properties for geofences and beacons and the AndroidManifest.xml file to make your app location aware. The com.ibm.mce.sdk.location.LocationManager class lets you enable and disable locations in the SDK.

To configure the IBM Mobile App Messaging Android SDK for geofences, follow these steps:

Step-by-step

  1. In the MCEConfig.json file, configure the following attributes:

    “syncInterval”: 300,

    The time interval between reference area geofence and beacon synchronizations with the server. Default is 300 seconds (5 minutes). The minimum allowed value is 300 seconds. If you try to set the syncInterval to a value that is lower than 300 seconds, the SDK resets to 300 seconds.

    “syncRadius”: 100000,

    The radius of the reference area. Default is 100000 meters (100 km).

    “locationResponsiveness”: 300,

    The time interval between location updates from the operating system to the SDK. The lower this interval is set, the more accurate and fast location updates are made, but power consumption is higher. Minimum is 60 seconds (1 minute). Default is 300 seconds (5 minutes).

    “minLocationsForSearch”: 1,

    The minimum number of geofences and beacons that the search must return. Default is 1.

    “maxLocationsForSearch”: 20,

    The maximum number of geofences and beacons that the search must return. Default is 20.

    “providerPreferences”: [“gps”, “network”]

    The preferred provider method. Valid values are gps and network.

    “uuid”: “Your IBEACONS UUID”,

    The iBeacons UUID for your organization.

    “beaconForegroundScanDuration”: 5,

    The bluetooth scan duration when the application is in the foreground. The default is 5 seconds.

    “beaconForegroundScanInterval”: 30,

    The time between bluetooth scans when the application is in the foreground. The default is 30 seconds.

    “beaconBackgroundScanDuration”: 300,

    The bluetooth scan duration when the application is in the background. The default is 300 seconds (5 minutes).

    “beaconBackgroundScanInterval”: 1800,

    The time between bluetooth scans when the application is in the background. The default is 1800 seconds (30 minutes).

     

    The following code sample shows the MCEConfig.json from the sample app.

    { "baseUrl": "https://sdk.ibm.xtify.com/3.0",
    "appKey": {
    "prod":"YOUR APP KEY" },
    "senderId": "YOUR GCM PROJECT ID",
    "sessionsEnabled": true,
    "sessionTimeout": 20,
    "metricTimeInterval": 30,
    "loglevel": "error",
    "logfile": false,
    "location": {
    "sync": {
    "syncInterval": 300,
    "syncRadius": 100000,
    "locationResponsiveness": 300,
    "minLocationsForSearch": 1,
    "maxLocationsForSearch": 20,
    "providerPreferences": ["gps", "network"] },
    "ibeacon": {
    "uuid": "YOUR IBEACONS UUID",
    "beaconForegroundScanDuration": 5,
    "beaconForegroundScanInterval": 30,
    "beaconBackgroundScanDuration": 300,
    "beaconBackgroundScanInterval": 1800
    }
    }
    }
  2. Edit the AndroidManifest.xml file, as described in the following steps.

    1. To use locations, add the following permissions (BLUETOOTH and BLUETOOTH_ADMIN are needed only if you use beacons). On later versions of Android you also need to request these permissions explicilty from the user; see Requesting location permissions on Android for more details.
      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
      <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
      <uses-permission android:name="android.permission.BLUETOOTH" />
      <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    2. Add the following services:
      <service android:name="com.ibm.mce.sdk.location.LocationRetrieveService" />
      <service android:name="com.ibm.mce.sdk.location.GeofenceIntentService" />
      <service android:name="com.ibm.mce.sdk.location.LocationEventsIntentService" />
      <service android:name="com.ibm.mce.sdk.location.LocationSyncAlarmListener" />
      <service android:name="com.ibm.mce.sdk.beacons.MceBluetoothScanner" />
      <service android:name="com.ibm.mce.sdk.beacons.BeaconsVerifier" />
      <receiver android:name="com.ibm.mce.sdk.location.LocationUpdateCaller" />
    3.  To enable location support, use the enableLocationSupport method in the com.ibm.mce.sdk.location.LocationManager class. Do not call this method before the device is registered with the  Watson Campaign Automation server: 
      LocationManager.enableLocationSupport(context);

      Note: To disable location support, use disableLocationSupport in the com.ibm.mce.sdk.location.LocationManager class: 

      LocationManager.disableLocationSupport(context); 
    4. To receive location enter, exit, and dwell events, implement the onLocationEvent method in your subclass of MceBroadcastReceiver. The onLocationEvent is called whenever a geofence or beacon enter, exit, or dwell event occurs. The following code sample shows how to implement the method.
      @Override
      // location type is ibeacon or geofence
      // location event type is enter, exit or dwell
      public void onLocationEvent(Context context, MceLocation location, LocationType locationType, LocationEventType
      locationEventType) {
      Log.d(TAG, "Location event: "+locationType.name()+" "+locationEventType.name()+" id = "+location.getId());
      // Uncomment this line to have the device display its location for testing purposes.
      // Do not ship with this uncommented.
      // showNotification(context, locationType.name()+" "+locationEventType.name(), location.getId(), locationType.name());
      }

       

    5. To receive location enter, exit, and dwell events when the device location is updated, implement the onLocationUpdate method in your subclass of MceBroadcastReceiver. The onLocationUpdate method is called when the sdk receives a device location update. The following code sample shows how to implement the method. 

      @Override
      public void onLocationUpdate(Context context, Location location) {
      Log.d(TAG, "Location was updated "+location);
      }

Expected outcome

Location Universal Behavior events are available in Watson Campaign Automation queries and programs for Android apps.  For information about other advanced mobile app messaging features for Android apps, see the Documentation.

Go Back to the Mobile App Messaging home page.

 

Join The Discussion

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