Location Targeting

The location module of the Airship SDK is designed to be extremely flexible. You can use it to do all your location tracking, or you use it when you’re in need of a single location update. If neither one of those fits your needs, you can do your own location tracking and let us upload the events 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.

Installation

Location require adding the urbanairship-location module:


dependencies {
  def airshipVersion = "13.2.1"

  implementation "com.urbanairship.android:urbanairship-location:$airshipVersion"

  // Optional - Allows airship to use fused location
  implementation 'com.google.android.gms:play-services-location:17.0.0'
}

Location Permission

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.

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 the AirshipLocationManager manager.

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

// Allow location updates to continue in the background
AirshipLocationManager.shared().setBackgroundLocationAllowed(true);
// Enable location updates
AirshipLocationManager.shared().isLocationUpdatesEnabled = true

// Allow location updates to continue in the background
AirshipLocationManager.shared().isBackgroundLocationAllowed = true

Listening for Location Updates

Location updates can be listened for by adding a LocationListener to the AirshipLocationManager.

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
AirshipLocationManager.shared().addLocationListener(listener);

// Remove the listener when finished
AirshipLocationManager.shared().removeLocationListener(listener);
// Create a listener
val listener : LocationListener = LocationListener { location ->
    Log.i("Location", "New user location $location")
}

// Add the listener to UALocationManager
AirshipLocationManager.shared().addLocationListener(listener)

// Remove the listener when finished
AirshipLocationManager.shared().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 800 meters for minimum distance update interval and 5 minutes for minimum time update interval, and prefer wifi accuracy over GPS.

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

// Set the default continuous location request options
AirshipLocationManager.shared().setLocationRequestOptions(options);
val options = LocationRequestOptions.Builder()
        .setPriority(LocationRequestOptions.PRIORITY_BALANCED_POWER_ACCURACY)
        .setMinDistance(800f)
        .setMinTime(5, TimeUnit.MINUTES)
        .build()

// Set the default continuous location request options
AirshipLocationManager.shared().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
PendingResult<Location> locationRequest = AirshipLocationManager.shared().requestSingleLocation();

// Optionally you can cancel the request and the callback will not be called
locationRequest.cancel();
val locationRequest = AirshipLocationManager.shared().requestSingleLocation()

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

Recording Location

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 in your dashboard. Create a LocationEvent and add it to Analytics directly.