Location Targeting

The location component of the Airship library is designed to be extremely flexible. You can use it to do all of your location tracking or if you want you can just use it when you're in need of a single location update and if neither one of those fits your needs, you can do your own location tracking and let us upload them to your dashboard for you. So, let's get started integrating location into your application so you can start making extremely relevant, targeted pushes to your users.

Setup

In order to start using location in your app, you'll need to add a location permission to your AndroidManifest.xml.

AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

If approximate locations aren't good enough, request android.permission.ACCESS_FINE_LOCATION instead to access the GPS.

Enable Fused Location Services
dependencies {
  compile 'com.google.android.gms:play-services-location:15.0.1'
}

Apps targeting Android Marshmallow (API 23) and later will prompt users to grant permissions at runtime, instead of install time. Since users can revoke permissions at any time from the app Settings screen, your app needs to check that it has the permissions it needs every time it runs. See Permissions for more details.

Using Airship Location

Airship Location exposes a very simple, high-level API for requesting location.

The Airship SDK is compatible with Google Play Services' Fused Location Provider. Fused Location will automatically be used if Google Play Services is available on the device, is up to date, and the application was built with the Google Play Services dependency. Otherwise the standard Android location will be used, such as for Amazon devices. Google Play Services setup instructions can be found here.

Continuous Location Updates

Location updates are enabled or disabled by UALocationManager.setLocationUpdatesEnabled .

Enabling location updates
// Enable location updates
UAirship.shared().getLocationManager().setLocationUpdatesEnabled(true);

// Allow location updates to continue in the background
UAirship.shared().getLocationManager().setBackgroundLocationAllowed(true);

Continuing updates in the background is controlled by UALocationManager.setBackgroundLocationAllowed . Listening for background locations now requires both location updates enabled and background location allowed.

Location updates can be listened for by instantiating or extending the LocationListener class:

Listening for location updates
// Create a listener
LocationListener listener = new LocationListener() {
    @Override
    public void onLocationChanged(Location location) {
        Log.i("Location", "New user location " + location);
    }
});

// Add the listener to UALocationManager
UAirship.shared().getLocationManager().addLocationListener(listener);

// Remove the listener when finished
UAirship.shared().getLocationManager().removeLocationListener(listener);

Location Request Options

Location request options are modeled after the Fused Location Provider by specifying high level needs instead of low level criteria. The location request options will automatically be converted to either criteria when using the standard Android Location APIs or to a LocationRequest when using Fused Location Provider.

The location request options for location updates will automatically default to LocationRequestOptions.PRIORITY_BALANCED_POWER_ACCURACY for request priority, 800 meters for minimum distance update interval and 5 minutes for minimum time update interval.

LocationRequestOptions options = new LocationRequestOptions.Builder()
        .setPriority(LocationRequestOptions.PRIORITY_BALANCED_POWER_ACCURACY)
        .setMinDistance(800)
        .setMinTime(5, TimeUnit.MINUTES)
        .create();

// Set the default continuous location request options
UAirship.shared().getLocationManager().setLocationRequestOptions(options);

Single Location Requests

Single location requests can be made in addition to continuous location updates or by themselves to have more control over when location requests are made.

When a single location request is made, a PendingResult is returned. The PendingResult can be used to cancel the request or set a callback when the result is ready.

Example
LocationCallback locationCallback = new LocationCallback() {
    @Override
    public void onResult(Location location) {
        if (location != null) {
            Log.i("Location", "Single location request: " + location);
        } else {
            Log.i("Location", "Single request failed!");
        }
    }
};

Cancelable locationRequest = UAirship.shared()
                                     .getLocationManager()
                                     .requestSingleLocation(locationCallback);

// Optionally you can cancel the request and the callback will not be called
locationRequest.cancel();

Recording Location

 Note

Any location update from Airship's location module will automatically be recorded as a location event.

If you're using your own location tracking, you can still upload those events to Airship so you can view them on your dashboard. Track the location by calling recordLocation on Analytics . The location will be automatically batched and uploaded so you can view it in your dashboard.

UAirship.shared().getAnalytics().recordLocation(location);