Android Location Services

In the standard integration described in the Android integration guide Location Services are switched off. Details of how to turn on the xtremepush Location Services for Android are given below. This will allow you to add geo-fence or iBeacon regions related to your app on the xtremepush platform.This allows you to analyse your app audiences offline behaviour  and trigger notifications when they enter/exit/dwell at your locations.To turn on the XtremePush Location Services you must be sure that you call setEnableLocations(true) when initialising XtremePush in your activities onCreate method, as follows:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER").setEnableLocations(true).create(this);

This turns on both geo-fence and iBeacon monitoring. To enable each of these individually you can set the following options:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
    .setEnableGeo(true)
    .setEnableBeacons(true)
    .create(this); 

Fine Tuning Location Services

There is a number of methods that can be used to fine tune the services when initialising the XtremePush location services:

• setLocationUpdateTimeout()
• setLowPowerGeo()
• setBeaconLocationForegroundTimeout() and setBeaconLocationBackgroundTimeout()
• setBeaconForegroundScanDuration() or setBeaconBackgroundScanDuration()

setLocationUpdateTimeout()

What is the purpose of this method? It is used to set the location update timeout parameter in seconds and can improve the accuracy of detected entry and exit events from geo-fence regions.

• If a value is set then an additional GPS check will be performed at the interval specified. For example calling setLocationUpdateTimeout(10) will perform an additional check every 10 seconds. Such a value will achieve very good geo fence detection accuracy with some cost to battery life. This parameter is configurable so developers can find a trade off between accuracy and the impact on battery.
• If this function is not used, then the default setting is that a location check will be performed every 30 seconds.

To turn on the XtremePush Location Services additional GPS check at an interval of 10 seconds you would make the following call when initialising XtremePush in your activities onCreate method:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableLocations(true)
.setLocationUpdateTimeout(10)
.create(this);

setLowPowerGeo()

What is the purpose of this method? It can be used to disable the additional location checks described directly above.

• If this function is called with a true parameter then no additional location checks will be performed. This supersedes any usage of the setLocationUpdateTimeout() function.
• If this function is not called or if a false value is passed in as a parameter, then the additional location checks will be performed as described immediately above, in the description of the setLocationUpdateTimeout() function.

To turn on the XtremePush low-power geo-fence mode you would make the following call when initialising XtremePush in your activities onCreate method:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableGeo(true)
.setLowPowerGeo(true)
.create(this);

setBeaconLocationForegroundTimeout() and setBeaconLocationBackgroundTimeout()

These methods are used to set the interval between the end of one iBeacon scan and the start of another, in seconds. It can be used to vary the frequency of scans for iBeacons. This parameter is configurable so developers can find a trade-off between the resolution of beacon events and the impact on battery. Setting a lower value can improve the speed of detecting enter and exit events from beacon-fenced regions with some impact on battery.

The two functions allow the separate configuration of the iBeacon scanning interval for when the app is open in the foreground or running in the background. This allows developers to reduce the frequency of iBeacon scans if the app is not open in order to save battery life if desired.

The default value for this setting is that interval between the end of one beacon scan and the start of another will be 4 secs in both foreground and background mode. To manually turn on the XtremePush iBeacon scanning services and set the beacon location scan timeouts to 4 secs, you would make the following call when initialising XtremePush in your activities onCreate method:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableBeacons(true)
.setBeaconLocationForegroundTimeout(4.0)
.setBeaconLocationBackgroundTimeout(4.0)
.create(this);

setBeaconForegroundScanDuration() and setBeaconBackgroundScanDuration()

These methods are used to set the duration of each iBeacon scan, in seconds. This parameter is configurable so developers can find a trade-off between accuracy and the impact on battery. Setting a higher value can improve the accuracy of beacon detection with some impact on battery.

The two functions allow the separate configuration of the iBeacon scanning duration for when the app is open in the foreground or running in the background. This allows developers to reduce the duration of iBeacon scans if the app is not open in order to save battery life if desired.

The default value for this setting is that a beacon scan will run for 2.1 secs in both foreground and background mode. To manually turn on the XtremePush iBeacon scanning services and set the beacon location scan durations to 2.1 secs, you would make the following call when initialising XtremePush in your activities onCreate method:

// INITIALISE THE XTREMEPUSH CONNECTOR HERE
mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableBeacons(true)
.setBeaconForegroundScanDuration(2.1)
.setBeaconBackgroundScanDuration(2.1)
.create(this);

Recommended Settings

We have tested many variations of settings for accuracy and impact on battery. We have found the following settings give very good accuracy for geo and iBeacon with a low impact on battery:

.setEnableLocations(true)
.setLocationUpdateTimeout(30)
.setBeaconLocationForegroundTimeout(4.0)
.setBeaconLocationBackgroundTimeout(4.0)
.setBeaconForegroundScanDuration(2.1)
.setBeaconBackgroundScanDuration(2.1)

Location Services Dialogs

There are two functions that can be used to override the default settings in relation to runtime permission requests on Android 6 and to turning location services on, on the device:

• setRequestPermissions()
• setEnableLocationDialog()

setRequestPermissions()

iBeacon and location scanning both require a location runtime permission request, as of Android 6. By default, runtime permission requests are enabled in the SDK, for applications using location services and running on Android 6+. If this functionality is not desired, then setRequestPermissions(false) can be used to disable these permission requests. Here is an example of this:

mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableLocations(true)
.setRequestPermissions(false)
.create(this);

The same function can also be used to customise and localise the text in the request permission rationale dialog. This dialog shows if the user initially denies permission request and then reopens the app. The text in this dialog provides more context around the permission request and then allows the user to reopen the permission request again. The setRequestPermissions() function also takes two additional string parameters, which can be used to customise the title and message text of the dialog, as shown here:

mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableLocations(true)
.setRequestPermissions(true, "title", "message")
.create(this);

setEnableLocationDialog()

On Android, there is an option in the device settings to turn location services on or off. If this option is turned off, none of the apps running on the device will be able to check the location of the device itself. If locations are enabled in the Xtremepush integration then the SDK will check to see whether location services are turned on or not. In the situation where location services are disabled on the device the SDK will launch a popup asking you to enable them in the device settings. This popup can be disabled however if this functionality is not required, as shown here:

mPushConnector = new PushConnector.Builder("XTREME_PUSH_APP_KEY", "GOOGLE_PROJECT_NUMBER")
.setEnableLocations(true)
.setEnableLocationDialog(false)
.create(this);