Android location permissions

Location services will allow you to add geofence or iBeacon regions related to your app on the Xtremepush platform. This allows you to analyse your app audiences, visits to your locations and trigger notifications when they enter/exit/dwell at your locations.

Enable location services

In the standard Integration of the Android SDK, Location Services are switched off. To use location features you first need to add the permissions to your app by adding the following to your app manifest file:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Then you can turn on the location feature by calling setEnableLocations(true) when initialising the Xtremepush SDK in your activities' onCreate method:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableLocations(true)
    .create(this);

To turn on geofence and iBeacon monitoring individually, you can instead set the following options:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableGeo(true)
    .setEnableBeacons(true)
    .create(this);

Fine tuning Location Services

The methods listed in this section can be used to fine tune the Xtremepush location services.

We have tested many variations of settings for accuracy and impact on battery. The following settings represent the default values for each of these methods (explained further below), which we have found give very good accuracy for geofences 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 update timeout

The setLocationUpdateTimeout() method is used to set the location update timeout, which can improve the accuracy of detected entry and exit events from geofence regions. By default, a location check will be performed every 30 seconds.

Setting a value will cause an additional GPS check at the interval specified in seconds. For example calling setLocationUpdateTimeout(10) will perform an additional check every 10 seconds. Such a value will achieve very good geofence 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.

To set an additional GPS check at an interval of 10 seconds you would make the following call when initialising the SDK:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableLocations(true)
    .setLocationUpdateTimeout(10)
    .create(this);

Low power mode

The setLowPowerGeo() method can be used to disable the additional location checks described directly above.

If this method is called with a true parameter then no additional location checks will be performed. This supersedes any usage of the setLocationUpdateTimeout() method.

Location checks are enabled by default. If disabled by passing true to this method, they can be re-enabled by calling the method again with a false parameter.

To enable low-power geofence mode you would make the following call when initialising the SDK:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableGeo(true)
    .setLowPowerGeo(true)
    .create(this);

iBeacon scan timeout

The setBeaconLocationForegroundTimeout() and setBeaconLocationBackgroundTimeout() 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 methods 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 is 4 seconds interval between scans in both foreground and background mode. To manually turn on the Xtremepush iBeacon scanning services and set the beacon location scan interval to 4 seconds, you would make the following call when initialising the SDK:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableBeacons(true)
    .setBeaconLocationForegroundTimeout(4.0)
    .setBeaconLocationBackgroundTimeout(4.0)
    .create(this);

iBeacon scan duration

The setBeaconForegroundScanDuration() and setBeaconBackgroundScanDuration() 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 methods 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 2.1 seconds scan duration 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 seconds, you would make the following call when initialising the SDK:

mPushConnector = new PushConnector.Builder("XPUSH_APP_KEY", "GOOGLE_SENDER_ID")
    .setEnableBeacons(true)
    .setBeaconForegroundScanDuration(2.1)
    .setBeaconBackgroundScanDuration(2.1)
    .create(this);

Location Services Dialogs

The methods in this section can be used to override the default settings for the runtime permission requests on Android 6 and for turning on device location services.

Location permission request

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:

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

The same method can also be used to customise and localise the text in the request permission rationale dialog. This dialog shows if the user initially denies the 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() method also takes two additional string parameters, which can be used to customise the title and message text of the dialog:

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

Device location settings

There is an option in the Android 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 location services are enabled in the Xtremepush SDK then it will check to see whether location services are enabled. If location services are disabled on the device, the SDK will launch a prompt asking the user to enable them in the device settings. This prompt can be disabled if this functionality is not required:

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

Not using location

📘

SDK versions before 9.0.0

If you are using version of the SDK before version 9.0.0 this is how you would have previously stopped your app from requesting location permission by adding the following to your manifest file:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"  tools:node="remove"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove" />