Location Module

The Location module enables your iOS 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:

• iOS

Requirements

• Tealium for Swift (1.9.0+)

Sample App

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

Install

Install the Location module with Swift Package Manager, CocoaPods or Carthage.

Swift Package Manager (Recommended)

To install the Location module with SPM:

1. Add a Swift Package within Xcode or the command line tool using the repository: https://www.github.com/Tealium/tealium-swift

2. If using Xcode, select the TealiumLocation target in the installation process. If using the command line, add the TealiumLocation module in the list of dependencies within the Package.swift file.

The framework is auto-instantiated. It has a dependency on TealiumCore and requires a dispatcher (TealiumCollect or TealiumTagManagement). No additional import statements are necessary.

Learn more about the SPM installation for iOS.

CocoaPods

To install the Location module with CocoaPods add the following pod to your Podfile:

pod 'tealium-swift/TealiumLocation'

The framework is auto-instantiated. It has a dependency on the TealiumCore pod and requires a dispatcher (TealiumCollect or TealiumTagManagement). Learn more about the CocoaPods installation for iOS.

Carthage

To install the Location module with Carthage:

1. Go to the app target’s General configuration page in Xcode.

2. Add the following framework to the Embedded Binaries section:

   TealiumLocation.framework
   

   The framework is auto-instantiated. It has a dependency on TealiumCore and requires a dispatcher (TealiumCollect or TealiumTagManagement). No additional import statements are necessary. Learn more about the Carthage installation for iOS.

Initialize

Location tracking is enabled by default when the module is added to your app. Configuration options for location accuracy and geofencing are set using properties of an instance of TealiumConfig.

Permissions

To authorize your app to collect location information, add the following keys to your app’s Info.plist file:

• Privacy - Location When In Use Usage Description
• Privacy - Location Always and When In Use Usage Description

If the keys are not present, location requests fail immediately. Learn more about requesting authorization for location services.

Location Tracking

The Location module performs continuous location tracking. Location updates are based on two settings: accuracy and distance.

By default, only significant location updates are monitored. This results in fewer updates and less battery consumption.

To enable higher accuracy updates, set the useHighAccuracy property to true and set the updateDistance property to a value in meters at which to trigger updates.

func start() {
      let config = TealiumConfig(account: "ACCOUNT",
                                 profile: "PROFILE",
                                 environment: "ENVIRONMENT",
                                 datasource: "DATASOURCE",
                                 optionalData: nil)
      config.useHighAccuracy = true
      config.updateDistance = 150
      //...
  }

Geofencing

To enable geofencing, use one of the following methods to provide your geofence JSON file:

• Hosted URL
  Use your own hosted geofences file, provided as a URL to the property geofenceUrl.
  This option is recommended if you have overridden the publish settings URL or want to use Hosted Data Layer.

  config.geofenceUrl = "https://example.com/geofences.json"
  

• Local File
  Use a geofences file stored in your app by setting the property geofenceFileName. Omit the file extension.

  config.geofenceFileName = "geofences" // geofences.json
  

Additional Considerations

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 20 per device user across all running applications.

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.

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 or exiting a geofence. The following additional variables are sent to the data layer:

Variable Name	Type	Description	Example
tealium_event	String	The Tealium tracked geofence event	"geofence_entered" or "geofence_exited"
geofence_name	String	The name of the geofence region	"Tealium_San_Diego"
geofence_transition_type	String	The type of geofence transition event	"geofence_entered" or "geofence_exited"
movement_speed	String	The instantaneous speed of the device, measured in meters per second	"1.0"
location_timestamp	String	The recorded date/time (GMT) the user entered/exited the geofence region	"2020-01-28 16:29:46 +0000"

API Reference

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