IOS SWIFT

Install

Requirements

Sample Apps

Explore the iOS (Swift) sample apps to help familiarize yourself with the Tealium library, tracking methods, and best practice implementation

To abstract the Tealium implementation from the rest of your app, we recommend using a helper class. This gives you a single entry point from which to initialize and make tracking calls. It also allows you to update the code in your helper file, and not in every single View or Swift file.

Explore our sample helper class.

Install

The Tealium iOS library is divided into modules. It is recommended to install only the modules that you need in order to maintain a smaller resource footprint. Learn more about the modules available for iOS.

Install the Tealium for iOS library with Swift Package Manager, CocoaPods, or Carthage.

Swift Package Manager is the recommended and simplest way to install the Tealium Swift library:

  1. In your Xcode project, select File > Swift Packages > Add Package Dependency
  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 modules to install and add the modules to each of your app targets in your Xcode project, under Frameworks > Libraries & Embedded Content

Swift Package Manager has the following limitations:

  • Due to lack of mixed-language source in a single target, the CrashReporter and AutoTracking modules are not supported through the Swift Package Manager. Verify that you do not need these modules before using Swift Package Manager.
  • Restricting a target within a package to a specific platform is not possible. Modules such as TagManagement, which are only supported for iOS, also become available to non-iOS targets. Adding one of these modules to an non-iOS target causes the compiler throws errors due to unavailable system libraries.

CocoaPods

To install the Tealium for iOS library with CocoaPods (recommended):

  1. Add the Tealium Swift pod "tealium-swift" to your Podfile. It has a subspec for each module, each of which depends on the “Core” module. If you do not specify any subspecs, all modules are installed by default.

    # Uncomment the next line to define a global platform for your project
platform :ios, '9.0'

target 'CPodTest' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for CPodTest

  # new entry for Tealium pod
  pod 'tealium-swift' # all modules
  # pod 'tealium-swift/TealiumTagManagement' # to install individual modules only, use subspecs
end

  2. Once you have added your desired modules, run the following command:

    pod install

    If the command doesn’t find the correct Pods, try running the command pod repo update.

  3. Open your Xcode project using the .xcworkspace file (Do not use the .xcodeproj file).

  4. To import any number of modules, add the following import statement in the file you plan to instantiate Tealium from:

    import TealiumSwift

The following is the list of recommended modules to add to your podfile:

To disable specific modules from the Podfile, comment them out in the Podfile with # or delete the line.

# ...
# *** Recommended minimum:
# All pods depend on Core. Supports all platforms.
pod "tealium-swift/Core"
pod "tealium-swift/Lifecycle"
pod "tealium-swift/Collect" # for Server-side products, e.g. EventStream - usually this or TealiumTagManagement, but not often both
# OR
pod "tealium-swift/TagManagement" # for Tealium iQ
pod "tealium-swift/RemoteCommands"

# *** Optional modules: You may not need these modules. Enable as required.   *** #

# Provides Visitor Audience and Attiribute information back to the app
# pod "tealium-swift/VisitorService"

# iOS Only. Gathers app attribution data and advertising IDs.
# pod "tealium-swift/Attribution"

# iOS and tvOS only. Generally not recommended. See separate notes in module documentation.
# pod "tealium-swift/Autotracking"

# See separate notes in module documentation.
# pod "tealium-swift/Location"

# iOS only. Reports detailed crash information.
# Installs separate TealiumCrashReporter dependency (based on PLCrashReporter).
# pod "TealiumCrashModule"
# ...

Carthage

To install Tealium for iOS (Swift) with Carthage:

  1. Add the following to your Cartfile:

    github "tealium/tealium-swift"

  2. To produce frameworks for iOS, macOS, tvOS and watchOS, run the following command:

    carthage update

  3. To build only for a particular platform, such as iOS, and to speed up subsequent builds after the initial build, use Carthage’s --platform argument:

    carthage update --platform ios --cache-builds

  4. Drag the frameworks you require into your Xcode project’s General > Embedded Binaries section.

    Verify that the Tealium frameworks have been added to the Embedded Binaries section in your project settings, otherwise your app crashes at launch.

  5. Follow the instructions listed in the Carthage Getting Started documentation to add the relevant build phases scripts, to ensure you don’t run into any issues when submitting your app.

Importing Modules

The Tealium Swift SDK has been split up into separate modules/frameworks. This means you need only import the specific frameworks for the modules you need to use, which helps to reduce the binary size and, ultimately, increase your app’s performance.

Module import statements

import TealiumCore              // required for Tealium, TealiumConfig, TealiumInstanceManager
import TealiumTagManagement		  // required to dispatch track calls to Tealium IQ
import TealiumCollect			  // required to dispatch track calls to Tealium's Customer Data Hub
import TealiumRemoteCommands    // required if you need to interact with the Remote Commands API
import TealiumLifecycle         // required if you need to collect lifecycle events and associated data

Due to Carthage limitations, we had to choose between the convenience of importing the entire SDK, and the flexibility and performance gains of a fully modular install. The downside to this is that it’s necessary to add each module you wish to use individually.

  • Carthage builds all the modules and output the resulting .framework files into your Carthage build directory.
  • Delete any modules you don’t need, and drag the modules that you do need into Xcode.

See Modules for further details on recommended module lists.

Initialize

We recommend managing your Tealium instance by using a tracking helper class. This provides a single point of entry for the Tealium iOS library, and simplifies future upgrades.

To initialize Tealium, pass a TealiumConfig instance to the Tealium() constructor, as shown in the following example:

class TealiumHelper {
    static let shared = TealiumHelper()
    let config = TealiumConfig(account: "ACCOUNT",
                               profile: "PROFILE",
                               environment: "ENVIRONMENT",
                               datasource: "DATASOURCE")
    var tealium: Tealium?

    private init() {

        // add necessary config options
        config.batchingEnabled = true
        config.logLevel = .debug

        // add desired Collectors - no need to include if want all compiled collectors
        config.collectors = [Collectors.Lifecycle,
                             Collectors.Location,
                             Collectors.VisitorService]

        // add desired Dispatchers - no need to include if want compiled dispatchers
        config.dispatchers = [Dispatchers.TagManagement,
                              Dispatchers.RemoteCommands]

        tealium = Tealium(config: config)

        // optional post init processing
        tealium?.dataLayer.add("mykey", "myvalue", expiration: .forever)

    }

    public func start() {
        _ = TealiumHelper.shared
    }

    class func trackView(title: String, data: [String: Any]?) {    
      let tealView = TealiumView(title, dataLayer: data)
      TealiumHelper.shared.tealium?.track(tealView)
    }

    class func trackEvent(title: String, data: [String: Any]?) {
      let tealEvent = TealiumEvent(title, dataLayer: data)
      TealiumHelper.shared.tealium?.track(tealEvent)
    }
}

Mobile Publish Settings are enabled by default, and must be disabled if you don’t wish to use them. Configure the Mobile Publish Settings in iQ Tag Management, or disable them using config.shouldUseRemotePublishSettings = false.

Log Level

To set a log level, set the logLevel property on your TealiumConfig instance with one of the following values:

  • .silent
  • .fault
  • .error
  • .debug
  • .info

For debugging purposes, .debug is recommended, as shown in the following example:

config.logLevel = .debug

The default log type used is OSLog, but this is modifiable to use print by updating the logType property on the TealiumConfig object to .print like so:

config.logType = .print

It is also possible to add your own logger instead of using the TealiumLogger by conforming your Logger class to the TealiumLoggerProtocol and setting the instance of that class to the logger property on the TealiumConfig object. Here is an example:

class CustomLogger: TealiumLoggerProtocol {
	// ... conforming to the TealiumLoggerProtocol
	// plus your own custom methods
}

class TealiumHelper {
	let customLogger = CustomLogger()
	var tealium: Tealium?
	// ...

	private init() {
		config.logger = customLogger
		// ...
	}
}

AppDelegate Proxy

By default, the Tealium Swift library includes a proxy for your app’s AppDelegate which automatic deep links tracking and initiates a Tealium trace session from a deep link. If you don’t wish to use this feature, set the appDelegateProxyEnabled property to false on your TealiumConfig instance.

config.appDelegateProxyEnabled = false

Event Batching

Event Batching is either be configured locally on the TealiumConfig instance, or by using the Mobile Publish Settings. Local settings override remote settings.

This example enables event batching and sets the batch size and queue size.

class TealiumHelper {
	var tealium: Tealium?
	// ...

	private init() {
		config.batchingEnabled = true            // enable batching
		config.batchSize = 10                    // size of batch
		config.dispatchAfter = 25                // flush after every 25 events
		config.dispatchQueueLimit = 100          // 100 max queued events
		config.dispatchExpiration = 5            // events expire/delete after 5 days
		// ...
	}
}

The following options are available to customize event batching.

Property Description
batchingEnabled Enables or disables event batching (default: false).
batchSize Sets the amount of events to combine into a single batch request (max: 10).
dispatchAfter Sets the number of events after which the queue is flushed.
dispatchExpiration Sets the batch expiration in days. If the device is offline for an extended period, events older than this are deleted.
dispatchQueueLimit Sets the maximum number of queued events. If this number is reached, and the queue has not been flushed, the oldest events are deleted.

Tag Management

With Tag Management and event batching enabled, tracking calls are dispatched as individual JavaScript calls to the hidden WebView.

Configured tags are triggered individually, resulting in multiple requests per event leaving the device. This improves device performance by waking up the device less frequently than sending real-time events.

Tealium Collect

This endpoint currently only accepts batch data generated by the Tealium SDK, in a proprietary batch format.

Track