Install

The current Tealium for Swift SDK version is 2.x. For previous versions, see Swift 1.x or Objective-C. Swift code co-exists along side your existing Objective-C files in the same project, with full access to your Objective-C API, making it easy to adopt.

Requirements

• Xcode 7.0+
• iOS 9.0+, macOS 10.11+, watchOS 3.0+, or tvOS 9.2+
• Tealium iQ Mobile Profile
• Tealium Customer Data Hub account

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 (Recommended)

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 appear in the list, then reset your Swift package cache.
4. Select the modules to install, and select the app target you want the modules to be installed in.

If your project has more than one app target and needs Tealium Swift libraries in more app targets, you have to manually add them in the Frameworks and Libraries section.

To install Tealium Swift libraries in additional app targets:

1. Select your Xcode project in the Project Navigator.
2. In your Xcode project, select the app target under the TARGETS section.
3. Navigate to Frameworks and Libraries and select a Tealium Swift library to add it to your app target.

Swift Package Manager cannot limit a target in a package to a specific platform. For example, modules such as TagManagement, supported only by iOS, also become available to non-iOS targets. Although these modules will technically be available via SPM on XCode to non-iOS targets, adding the modules to those targets will cause the compiler to throw errors due to unavailable system libraries. This limitation should not impact users because iOS-exclusive modules should only be added to iOS apps.

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, '11.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/TagManagement' # 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
   

Recommended Podfile

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. Import only the specific frameworks for the modules you need to reduce the binary size and increase your app’s performance.

Module import statements

• TealiumCore - required for Tealium, TealiumConfig, TealiumInstanceManager
• TealiumTagManagement - required to dispatch track calls to Tealium iQ
• TealiumCollect - required to dispatch track calls to Tealium’s Customer Data Hub
• TealiumRemoteCommands - required if you need to interact with the remote commands API
• TealiumLifecycle - required if you need to collect lifecycle events and associated data

import TealiumCore
import TealiumTagManagement
import TealiumCollect
import TealiumRemoteCommands
import TealiumLifecycle

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

To initialize Tealium, pass a TealiumConfig instance to the Tealium() constructor.

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

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
        config.collectors = [Collectors.Lifecycle,
                             Collectors.Location,
                             Collectors.VisitorService]

        // add desired Dispatchers
        config.dispatchers = [Dispatchers.TagManagement,
                              Dispatchers.RemoteCommands]

        tealium = Tealium(config: config)

        // optional post init processing
        tealium?.dataLayer.add(key: "mykey", value: "myvalue", expiry: .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)
    }
}

Replace the following:

• ACCOUNT: your Tealium account name you want to use to initialize the library in lowercase.
• PROFILE: your Tealium profile name you want to use to initialize the library in lowercase.
• ENVIRONMENT: the environment where you want to initialize Tealium.
• DATASOURCE: the Tealium data source you want to use.

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:

config.logLevel = .debug // or .info, .error, .fault, .silent

For debugging purposes, .debug is recommended.

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

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 automatically tracks deep links and initiates Tealium trace sessions using the Mobile Trace Tool. 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.

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.