• Platforms
  • Partners
  • Forums
  • 日本語
  • TLC Tealium Learning Center Tealium Learning
    Community
  • Discussions & Ideas Dicussions & Ideas
  • Product Guides Product Guides
  • Knowledge Base Knowledge Base
  • Developer Docs Developer Docs
  • Education Education
  • TLC Blog TLC Blog
  • Support Desk Support Desk
  • CDH Customer Data Hub Customer Data Hub
  • Mobile
  • Getting Started
    • Overview
    • Quick Start Guide
    • Mobile Concepts
    • Client-Side
    • Server-Side
    • Tracking Webviews
    • Data Layer
    • Consent Management
    • Event Batching
    • User Location and Geofencing
    • Media Tracking
    • Deep Links
    • Timed Events
    • Trace
    • Hosted Data Layer
    • Adobe Visitor Service Module
    • Feature Comparison
    • Troubleshooting
  • Remote Commands
    • Overview
    • How It Works
    • Integrations
      • Adjust
      • AppsFlyer
      • Branch
      • Braze
      • Contentsquare
      • Facebook
      • Firebase
      • Kochava
      • Usabilla
  • Android (Java)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Module
      • Optimizely X Tracking Module
    • Android TV
    • Android Wear
    • API Reference
      • ConsentManager
      • DataSources
      • Lifecycle
      • Tealium
      • Tealium.Config
      • TealiumLocation
    • Release Notes
  • Android (Kotlin)
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • Identity Resolution
    • Module List
      • Ad Identifier Module
      • AutoTracking Module
      • AdobeVisitorService Module
      • Collect Module
      • Collectors Module
      • Crash Reporter Module
      • In-App Purchase Module
      • Install Referrer Module
      • Lifecycle Tracking Module
      • Location Manager Module
      • Media Module
      • RemoteCommands Module
      • Tag Management Dispatcher Module
      • Visitor Service Module
    • Android TV
    • API Reference
      • ConsentCategory
      • ConsentManager
      • CurrentVisit
      • DataLayer
      • Lifecycle
      • LocationManager
      • Media
      • Tealium
      • TealiumConfig
      • VisitorProfile
      • VisitorService
    • Release Notes
  • Cordova 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Module List
      • Ad Identifier Module
      • Crash Reporter Module
      • Install Referrer Module
    • API Reference
    • Release Notes
  • Cordova 2.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Flutter 1.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
    • Release Notes
  • Flutter 2.x
    • Overview
    • Install
    • Track
    • Consent Management
    • Data Management
    • API Reference
      • Tealium
      • TealiumConfig
      • VisitorProfile
    • Release Notes
  • iOS (Objective-C)
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • Consent Management
    • Tag Management
    • Module List
      • Lifecycle Tracking Module
    • tvOS
    • watchOS
    • API Reference
    • Release Notes
  • iOS (Swift) 1.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Data Management
    • App Extensions
    • Identity Resolution
    • Consent Management
    • Modules
    • Module List
      • AppData Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DataSource Module
      • DefaultStorage Module
      • Delegate Module
      • DeviceData Module
      • DispatchQueue Module
      • FileStorage Module
      • Lifecycle Module
      • Location Module
      • Logger Module
      • PersistentData Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
      • VolatileData Module
    • Feature Comparison
    • Working with Objective-C
    • API Reference
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManagerDelegate
      • TealiumConsentManager
      • TealiumInstanceManager
      • TealiumPersistentData
      • TealiumVolatileData
      • Tealium
    • Release Notes
  • iOS (Swift) 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • App Extensions
    • Identity Resolution
    • Modules
    • Module List
      • AppData Module
      • AdobeVisitorService Module
      • Attribution Module
      • AutoTracking Module
      • Collect Module
      • Connectivity Module
      • CrashReporter Module
      • DeviceData Module
      • In-App Purchase Module
      • Lifecycle Module
      • Location Module
      • Media Module
      • RemoteCommands Module
      • TagManagement Module
      • VisitorService Module
    • Working with Objective-C
    • API Reference
      • LocationModule
      • MediaSession
      • Tealium
      • TealiumConfig
      • TealiumConsentCategories
      • TealiumConsentManager
      • TealiumDataLayer
      • TealiumInstanceManager
    • Release Notes
  • NativeScript
    • Overview
    • Install
    • Track
    • API Reference
      • Tealium
      • TealiumConfig
    • Release Notes
  • React Native 1.x
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • React Native 2.x
    • Overview
    • Install
    • Track
    • Location Module
    • API Reference
    • Release Notes
  • Unity 1.x
    • Overview
    • Install
    • Track
    • API Reference
  • Unity 2.x
    • Overview
    • Install
    • Track
    • API Reference
  • Xamarin 1.x
    • Overview
    • Install
    • Track
    • Data Management
    • Consent Management
    • API Reference
    • Release Notes
  • Xamarin 2.x
    • Overview
    • Install
    • Track
    • Data Layer
    • Consent Management
    • API Reference
    • Release Notes
  • Web
  • Getting Started
    • Overview
    • Quick Start Guide
    • Web Concepts
    • Data Layer
      • An Introduction to the Data Layer
      • How the Data Layer Works for Websites
      • Data Layer Best Practices
      • Definitions
        • Retail
        • Publisher
        • Hotel
        • Travel
        • Basic Video Tracking
  • Adobe Launch
    • Overview
    • Install
    • Data Layer
  • AMP
    • Overview
    • Install
    • Track
    • Data Layer
  • Angular
    • Overview
    • Install
    • Track
    • API Reference
  • Google Tag Manager
    • Overview
    • Install
    • Data Layer
  • JavaScript (Web)
    • Overview
    • Install
    • Track
    • Data Layer
    • Universal Data Object (utag_data)
    • Universal Tag (utag.js)
    • Data Layer Object (b)
    • Single-Page Applications
    • Settings
    • Debugging
    • API Reference
      • Cookie Functions
      • GDPR Functions
      • Tracking Functions
      • Utility Functions
    • Release Notes
  • Server
  • C#
    • Overview
    • Install
    • Track
    • Data Layer
    • API Reference
    • Release Notes
  • HTTP API
    • Overview
    • Endpoint
    • Data Layer
  • Java
    • Overview
    • Install
    • Track
    • API Reference
    • Release Notes
  • Node
    • Overview
    • Install
    • Track
    • API Reference
  • Python
    • Overview
    • Install
    • Track
    • API Reference
  • Roku
    • Overview
    • Install
    • Track
    • API Reference
  • Ruby
    • Overview
    • Install
    • Track
    • API Reference
ANDROID JAVA/MODULE LIST

Location Module

Provides device location data for your events and the ability to add geofences around points of interest.

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.

Variable Name Type Description Example
latitude String The latitude of the user’s most recently recorded location "32.906119"
longitude String The longitude of the user’s most recently recorded location "-117.2367"
location_accuracy String The accuracy setting for the location module, such as "high" or "low" "high"

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:

Variable Name Type Description Example
tealium_event String The Tealium tracked geofence event "geofence_entered", "geofence_exited", or "geofence_dwell"
geofence_name String The name of the geofence region "Tealium_San_Diego"
geofence_transition_type String The type of geofence transition event "geofence_entered", "geofence_exited", or "geofence_dwell"

API Reference

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

"Lifecycle Tracking Module "
Previous
Lifecycle Tracking Module
Next
Optimizely X Tracking Module
"Optimizely X Tracking Module"

 

Was this article helpful?

This page was last updated: June 23, 2021      

Thank you for your feedback!

Table of Contents

  • Supported Platforms
  • Requirements
  • Sample App
  • Install
    • Maven
    • Manual
  • Initialize
  • Location Tracking
    • Location Permissions
    • Last Known Location
  • Geofencing
  • Additional Considerations
  • Data Layer
  • API Reference
  • Platforms
  • Partners
  • Forums
  • Mobile
  • Getting Started
  • Remote Commands
  • Android (Java)
  • Android (Kotlin)
  • Cordova 1.x
  • Cordova 2.x
  • Flutter 1.x
  • Flutter 2.x
  • iOS (Objective-C)
  • iOS (Swift) 1.x
  • iOS (Swift) 2.x
  • NativeScript
  • React Native 1.x
  • React Native 2.x
  • Unity 1.x
  • Unity 2.x
  • Xamarin 1.x
  • Xamarin 2.x
  • Web
  • Getting Started
  • Adobe Launch
  • AMP
  • Angular
  • Google Tag Manager
  • JavaScript (Web)
  • Server
  • C#
  • HTTP API
  • Java
  • Node
  • Python
  • Roku
  • Ruby