Location Module

The Location module enables your Android app to receive location information and the ability to configure and monitor geofences. Learn more about location tracking and geofencing.

Supported Platforms

The following platforms are supported:

• Android
• Android TV
• Android Wear

Requirements

• Tealium for Android (5.6.0+)
• Google Play Services Location (11.0.0+)

This module supports Firebase Cloud Messaging.

Sample App

Explore the Android Location module sample app to familiarize yourself with our library, tracking methods, and best practice implementation.

Install

Install the module with Maven (recommended) or manually. After you install, add the following import statement:

import com.tealium.location.TealiumLocation;

Maven

To install the module using Maven:

1. In your project’s top-level build.gradle file, add the following Maven repository:

   maven {
     url "https://maven.tealiumiq.com/android/releases/"
   }

2. In your project module’s build.gradle file, add the Maven dependencies for the Tealium library, Location module, and Google Play Services Location API:

   dependencies {
     implementation 'com.tealium:library:5.8.0'
     implementation 'com.tealium:location:1.0.0'
     runtimeOnly 'com.google.android.gms:play-services-location:17.0.0'
   }

Manual

To install the Location module manually:

1. Download the Location module

2. In your top-level build.gradle file, verify the following:

   allprojects {
     repositories {
         ...
         google()
         flatDir {
             dirs 'libs'
         }
         ...
     }
   }

3. Copy the file tealium.location-1.0.0.aar into your project’s <PROJECT_ROOT>/<MODULE>/libs directory.

4. Add the Tealium library dependency to your project module’s build.gradle file:

   dependencies {
     // only required if you do not already have this reference
     implementation(name:'tealium-5.6.0', ext:'aar')
     // location module reference
     implementation(name:'tealium.location-1.0.0', ext:'aar')
     // Google's Location Services API reference
     runtimeOnly 'com.google.android.gms:play-services-location:17.0.0'
   }

Initialize

Initialize the Location module by passing a Tealium instance name to TealiumLocation.setupInstance().

Set<String> tealiumInstances = new HashSet<>();
tealiumInstances.add(TealiumHelper.TEALIUM_MAIN);

mInstance = TealiumLocation.setupInstance(this, tealiumInstances);

Location Tracking

The Location module performs continuous location tracking automatically when it is enabled and location permissions are granted. Location updates are based on two settings: accuracy and time interval.

Accuracy may be set to high or low. High accuracy corresponds to the Android setting PRIORITY_HIGH_ACCURACY and low accuracy corresponds to the Android setting PRIORITY_BALANCED_POWER_ACCURACY.

Learn more about Android location accuracy settings.

The time interval between location updates is set with a value in milliseconds. Use the highest possible value that is still useful to your app. The interval value is passed to the Android methods setInterval() and setFastestInterval().

Learn more about Android location interval settings.

Start location tracking by calling TealiumLocation.startLocationUpdates(). Set the first parameter to true for high accuracy and false for lower accuracy tracking.

The following example uses high accuracy and a time interval of 60000 milliseconds (60 seconds):

TealiumLocation.getInstance().startLocationUpdates(true, 60000);

Disable continuous tracking by calling the methods TealiumLocation.destroyInstance() or TealiumLocation.stopLocationUpdates().

Location Permissions

To grant location permissions in your app:

1. Set the constant variable for the location request code:

   public static final int LOCATION_REQUEST_CODE = 101;

2. Add the following method in your app’s MainActivity class:

   public void requestLocationPermission() {
       if (ContextCompat.checkSelfPermission(getApplicationContext(),
       Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
           ActivityCompat.requestPermissions(this,
             new String[]{
                 Manifest.permission.ACCESS_FINE_LOCATION,
                 Manifest.permission.ACCESS_COARSE_LOCATION
             }, LOCATION_REQUEST_CODE);
       }
   }

3. Call the requestLocationPermission() method within the onCreate() method of the MainActivity class:

   if ((ContextCompat.checkSelfPermission(getApplicationContext(),
     Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
     && ContextCompat.checkSelfPermission(getApplicationContext(),
     Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
         requestLocationPermission();
   }

4. Optionally, to verify that location permissions are granted, override the onRequestPermissionsResult() method:

   @Override
   public void onRequestPermissionsResult(int requestCode,
     String[] permissions,
     int[] grantResults) {
       String message;
       if (requestCode == LOCATION_REQUEST_CODE) {
           // If request is cancelled, the result arrays are empty.
           if ((grantResults.length > 0) && (grantResults[0]
             == PackageManager.PERMISSION_GRANTED)) {
               message = "Location Permission Granted";
           } else {
               message = "Location Permission Not Granted";
           }
       } else {
           message = "Location Permission Not Granted";
       }
       showToast(message);
   }
   
   private void showToast(String message) {
     Toast.makeText(getApplicationContext(),
     message,
     Toast.LENGTH_LONG).show();
   }

Last Known Location

When continuous tracking is disabled, request the last known location with the method TealiumLocation.requestDeviceLastLocation(). This method relies on the location client being used by other apps on the device for accuracy. If no other apps are receiving location updates, then the method returns the last known location (or null if the location is not available).

TealiumLocation.getInstance().requestDeviceLastLocation();

Geofencing

To initialize with geofencing enabled, use one of the following methods to provide your geofence JSON file to the setup method:

• Hosted URL
  Use your own hosted geofences file provided as a URL to the method TealiumLocation.setupInstanceWithUrl().
  This option is recommended if you have overridden the publish settings URL or want to use Hosted Data Layer.

  TealiumLocation.setupInstanceWithUrl(this, tealiumInstances, "https://example.com/geofences.json");

• Local File
  Use a geofences file stored in the Assets directory of your app with TealiumLocation.setupInstanceWithFile().

  TealiumLocation.setupInstanceWithFile(this, tealiumInstances, "geofences.json");

Additional Considerations

Battery Optimization Features
Android devices that implement battery optimization features may interfere with geofence monitoring, leading to events not firing.

BroadcastReceiver
A GEOFENCE_EVENT broadcast is sent when a geofence transition type is triggered. Android only calls the first BroadcastReceiver for this particular broadcast, even if multiple are defined. For third party SDKs that handle the GEOFENCE_EVENT broadcast, implement a “proxy” BroadcastReceiver that calls the onReceive() method of each individual receiver for the GEOFENCE_EVENT broadcast.

Initializing Geofences
If a user is within a geofence at the time of creation, the "enter" transition event does not fire. This is because "exit" and "enter" transition events are fired when crossing the perimeter and not when materializing inside.

Latency:
When using the geofencing capabilities, take the following into account:

• The geofence service does not continuously query for location, so latency is expected when receiving alerts. The latency is typically less than 2 minutes, but if background location limits are set or if the device has been stationary for a while, the latency increases.
• The geofence service depends on the network location provider and a data connection. If there is no reliable network connectivity inside the geofence, alerts may not be triggered.
• If Wi-Fi is turned off on the device, your application might never receive geofence alerts depending on several settings including the radius of the geofence, the device model, or the Android version. In Android 4.3+ provides the capability of “Wi-Fi scan only mode” which allows users to disable Wi-Fi and still receive a reliable network location. It is recommended to prompt the user to enable this setting.

Number of Active Geofences
Geofences are added and removed dynamically, using as few resources as possible. There is no limit to the number of geofences defined, but the number of active geofences is limited to 100 per device user across all running applications.

Data Layer

The following variables are populated by the Location module as part of the mobile data layer. These variables are included automatically in each tracking call from the library.

During geofencing, a tracking call containing location data is sent when the transition state of the user changes. Transition state changes include a user entering, exiting, or dwelling within a geofence for a specified duration of time. You must set the duration of loitering before the dwelling alert is sent using the Android method setLoiteringDelay().

The following variables are sent to the data layer:

API Reference

For the reference of methods used in the Location module, see the TealiumLocation class in the Tealium SDK for Android API.