Overview

Skill Level: Any

You can enable location support for geofences and beacons in the IBM Mobile App Messaging SDK for Android apps developed in Xamarin.

Prerequisites

Before configuring the IBM Mobile App Messaging 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 in the AndroidManifest.xml file lets you enable and disable locations in the SDK.

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.

To configure the SDK for locations, 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 the value to 300 seconds.

    “syncRadius”: 10000,
    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:
      <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" />
      <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); 
  3. (Optional) If you want to be notified when a geofence or beacon event occurs, implement the following delegates:

    Note: If you implemented the delegates when configuring locations for iOS, you can skip this step. 

     

    Beacon entry:

    SDK.Instance.BeaconEntered += (beaconRegion) => {
    // use beaconRegion.Minor
    // use beaconRegion.Major
    }

     

    Beacon exit:

    SDK.Instance.BeaconExited += (beaconRegion) => {
    // use beaconRegion.Minor
    // use beaconRegion.Major
    }

     

    Geofence entry:

    SDK.Instance.GeofenceEntry += (geofence) => {
    // use geofence.Latitude
    // use geofence.Longitude
    // use geofence.Radius
    }

     

    Geofence exit:

    SDK.Instance.GeofenceExited += (geofence) => {
    // use geofence.Latitude
    // use geofence.Longitude
    // use geofence.Radius
    }
     

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 Xamarin, 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 *