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 and an example of the geofencing feature.

Install

Install the Location module with Swift Package Manager, CocoaPods or Carthage. The Location module requires a dispatcher (TealiumCollect or TealiumTagManagement) to transmit location events.

Swift Package Manager (Recommended)

Supported in version 1.9.0+, the Swift Package Manager is the recommended and simplest way to install the Tealium Swift library:

1. In your Xcode project, select File > Add Package Dependencies.
2. Enter the repository URL: https://github.com/tealium/tealium-swift
3. Configure the version rules. Typically, Up to next major is recommended. If the current Tealium Swift library version does not appears in the list, then reset your Swift package cache.
4. Select the Location module from the list of modules to install and add it each of your app targets in your Xcode project, under Frameworks and Libraries.

Learn more about the Swift Package Manager installation for iOS.

CocoaPods

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

pod 'tealium-swift/Location'

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
   

Learn more about the Carthage installation for iOS.

Initialize

To initialize the module, verify that it’s specified on the TealiumConfig collectors property

config.collectors = [Collectors.Location]

Additional options for location accuracy and geofencing are also configurable for your TealiumConfig instance.

Review the Collectors documentation to understand how to correctly specify the collectors you require.

Authorization

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.

If you do not already request location authorizaiton within your current implementation, you can use the Location module’s API method requestAuthorization() in the Tealium completion callback like so:

func start() {
      //...
      tealium = Tealium(config: config) { _ in
      		self.tealium?.location?.requestAuthorization()
      }
  }

Approximate Location Tracking (iOS 14+)

Apple iOS 14+ provides an app setting for sharing your approximate location rather than your precise location. This method is recommended if your app requires precise location, and if the user initially disabled precise location tracking through their device settings.

If you are not already requesting temporary full authorization in your codebase, use the Tealium helper method requestTemporaryFullAccuracyAuthorization shown in the following example which requests temporary full accuracy.

func start() {
    //...
    tealium = Tealium(config: config) { _ in
      guard let location = self.tealium?.location else {
          return
      }
      if location.isAuthorized {
          location.requestTemporaryFullAccuracyAuthorization(purposeKey: "NearStore")
      } else {
          location.requestAuthorization()
      }
    }
}

The String parameter purposeKey corresponds to the key in the NSLocationTemporaryUsageDescriptionDictionary dictionary of your app Info.plist file, as shown in the following example:

    <key>NSLocationTemporaryUsageDescriptionDictionary</key>
    <dict>
        <key>NearStore</key>
        <string>In order to send you discounts when you are near a store</string>
    </dict>

Learn more about requesting temporary full authorization.

Location Tracking

The Location module performs continuous location tracking once the user has authorized location services. Location updates are based on two settings: accuracy and distance.

If you disable the geofence feature, only significant location updates are monitored by Apple’s startMonitoringSignificantLocationChanges() method, which results in fewer updates and less battery consumption. This method is called if either property config.geofencesTrackingEnabled or config.useHighAccuracy are set to false, otherwise the Apple’s startUpdatingLocation method is called

The geofence feature is enabled by default and location updates are more frequent to provide better accuracy. To enable or disable more frequent location updates, set the useHighAccuracy property.

If you would like a more accurate location and distance setting, set the updateDistance property to a value in meters at which to trigger updates.

There is also an extended accuracy setting, desiredAccuracy that specifies the level of accuracy which the app desires to receive. This is the similar to the CLLocationManager desiredAccuracy property. In iOS 14+, the default value is .reduced and in previous versions it is .nearestHundredMeters.

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

Geofencing

Geofencing is enabled by default, and to configure geofences, 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

To disable geofencing set the geofenceTrackingEnabled property:

config.geofenceTrackingEnabled = false

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.

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:

API Reference

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