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.
Before configuring the 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 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 Mobile app messaging Android SDK for geofences, follow these steps:
In the MCEConfig.json file, configure the following attributes:
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.
The radius of the reference area. Default is 100000 meters (100 km).
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).
The minimum number of geofences and beacons that the search must return. Default is 1.
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.
The bluetooth scan duration when the application is in the foreground. The default is 5 seconds.
The time between bluetooth scans when the application is in the foreground. The default is 30 seconds.
The bluetooth scan duration when the application is in the background. The default is 300 seconds (5 minutes).
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.
Edit the AndroidManifest.xml file, as described in the following steps.
- 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.
- Add the following services:
- ¬†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¬† Acoustic Campaign server:¬†
Note: To disable location support, use disableLocationSupport in the com.ibm.mce.sdk.location.LocationManager class:¬†
- 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.
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.¬†