Controlling the Monitoring of Bitplaces

Bitplaces monitoring is performed by tracking the device's location and by listening to signals from beacon bitplaces in the vicinity.

The monitoring is performed by a background service (com.bitplaces.sdk.android.BitplacesService), but you don't need to interact with this service directly. Rather, you can control it from your BitplacesSDK instance.

The following three instance methods let you control and inquiry about the status of the bitplaces monitoring:

1
2
3
4
5
BitplacesSDK bpSDK = BitplacesSDK.getInstance(); // provided it has been initialized previously

bpSDK.startMonitoringBitplaces();
bpSDK.stopMonitoringBitplaces();
boolean isMonitoringActive = bpSDK.isBitplacesMonitoringActive();

Bitplaces monitoring involves listening for IN and OUT events coming from two kinds of bitplaces:

  • Geo bitplaces, represented as instances of Bitplace, are tracked with the help of the device's location determining hardware (including, when available, the GPS, WiFi and cellular radios).
  • Beacon bitplaces, represented as instances of BeaconBitplace (which inherits from Bitplace), are tracked with the help of the device's Bluetooth Low Energy radio and are available only in devices with BLE hardware support and Android 4.3 and newer.

The SDK actively caches information about Geo- and Beacon bitplaces around the device, and retrieves that information when the device is within an area for which this data has been cached recently. For that reason, during development and testing, if any changes, additions or deletions are made via the Cloud Management to an area in which the SDK is being tested, it's strongly recommended to uninstall and reinstall the app in which the SDK is being integrated and tested or at least to delete the app's locally cached data to ensure that the SDK will be working with the most up-to-date state of the test areas.

NOTE: If your app is targeting Android 6.0 or later (API level 23 or higher), you will have to deal with the ACCESS_FINE_LOCATION permission at run time: check that the user has granted the permission and, if not, request it to the user at run time before invoking startMonitoringBitplaces(). If you call startMonitoringBitplaces() but the user has not granted the ACCESS_FINE_LOCATION permission, the SDK will ignore this call and won't start monitoring. We've left the responsibility of requesting the run time permission to your app instead of making the SDK request it itself because:

  • this way you can determine exactly when to request it in the user flow of your app, and you can show the user a customized message explaining why you are requesting permission to acess their location;
  • the Android APIs used to request permissions at run time expect to be called from your Activity and will deliver their results to it;
  • we are letting it up to your application logic to decide what else to do with a grant or a denial of permission from the user, particularly if you are accessing the user's location for your own purposes too.

Note that it's not strictly necessary that you include the ACCESS_FINE_LOCATION permission in your application manifest, as the SDK library's manifest includes it already and it will be merged with your own one.

Refer to Requesting Permissions at Run Time in the Android documentation for more information about how to check for and request permissions.

Configuring the Monitoring of Bitplaces

It's possible to set a number of parameters to more finely control the bitplaces monitoring process. These parameters can be set by building a new instance of the MonitoringPreferences class and passing it to setMonitoringPreferences(). The preferences will be effective the next time location tracking is started.

The set preferences are persisted so it's not necessary to set them each time your app is launched.

This configuration mechanism can be used, for example, to tell the SDK whether to monitor geofences and / or beacon bitplaces, how to treat mock locations, how frequently to scan for beacons, etc.

For this example, we will tell the SDK to use Google Play services to detect both geo bitplaces and beacon bitplaces and to ignore any mock locations reported by the system:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import com.bitplaces.sdk.android.MonitoringPreferences;
import static com.bitplaces.sdk.android.MonitoringPreferences.*;

// [...]

MonitoringPreferences preferences = new MonitoringPreferences.Builder()
        .setMonitoringMode(MONITORING_MODE_GEO_BITPLACES | MONITORING_MODE_BEACON_BITPLACES)
        .setMockLocationsPolicy(MOCK_LOCATIONS_POLICY_IGNORE_PLAY_SERVICES_MOCK_LOCATIONS)
        .build();

BitplacesSDK bpSDK = BitplacesSDK.getInstance(); // provided it has been initialized previously
bpSDK.setMonitoringPreferences(preferences);

One important option is whether you want to allow the Bitplaces Android SDK to detect beacon bitplaces independently of the geographical location that has been configured for them in the Cloud Management. This allows the SDK to recognize even those beacons which are far away from their expected location. This behavior is determined by the value returned by the getEnforceExpectedBeaconLocation() method of MonitoringPreferences. Its current default is false, which means that the SDK will listen and react to beacons regardless of their geographical location. If you want the SDK to detect beacons only when they are at or near the location where they are expected to be found, that is, if you want to disable location independent beacon detection, you can pass true to the setEnforceExpectedBeaconLocation(boolean) method of MonitoringPreferences.Builder when constructing a monitoring preferences instance, then pass that instance to the setMonitoringPreferences(preferences) method of the BitplacesSDK instance.

Remember that the set monitoring preferences will become effective the next time that bitplaces monitoring is started.

For more information, refer to the MonitoringPreferences API documentation.