Adding Tealium to Your Swift App

[#1]

NOTE: This article is deprecated. Please see: https://community.tealiumiq.com/t5/Swift/tkb-p/swift

This guide shows how to add Tealium to your Swift app to track user activity. Before you begin, here's a video introduction to the platform:

Table of Contents Placeholder

Requirements

• Tealium account enabled for AudienceStream, DataAccess, or EventStream
• Swift 3.0+
• Xcode 8.0+ 

Add the Dependency

The code for the Tealium Swift library can be easily installed using Carthage or downloaded from on Github. The repository contains the following modules:

• Core (tealium/core)- (required) The main module.
• AppData (tealium/appdata) - Adds event attributes  device_uuid and tealium_vid to tracked data (required for AudienceStream visitor stitching).
• Attribution (tealium/attribution) - Adds event attribute device_advertising_id (identifierForVendor) to tracked data. Please note that using this module requires an additional app store submission step.
• Collect (tealium/collect) - (highly recommended) Used to activate tracking calls to Tealium Collect.
• TagManagement (tealium/tagmanagement) - (highly recommended for Tealium iQ users) Used to implement JavaScript-based tracking tags in Swift apps.
• Logger (tealium/logger) - Enables logging of warnings, errors, and other helpful messages.
• PersistentData (tealium/persistentdata) - Enables the ability to add persistent data to tracking calls.
• VolatileData (tealium/volatiledata) - Enables the ability to add persistent session data to tracking calls.

Using Carthage

Carthage is a simple way to manage dependencies in Swift. Install Carthage manually or via Homebrew with the following terminal command:

brew install carthage

Then add the following entry to the Cartfile in your project:

github "tealium/tealium-swift" 

Then update from the terminal with:

carthage update

This will produce frameworks for the following platforms:

• iOS
• macOS
• tvOS
• watchOS 

To build only for a particular platform, use Carthage's --platform argument:

carthage update --platform ios

The Carthage built frameworks do not include the Attribution module by default.

Manually

The code for the Tealium Swift library is stored on Github. You must download and install the library.

• Download: Tealium for Swift

Import the Tealium folder into your project and add the desired modules. The library employs a drag-and-drop modular architecture when the source files are referenced directly. Each subfolder within tealium-swift/tealium contains all the files related to that module.  The Core submodule is required and the Collect submodule is highly recommended.

To disable a previously added module, either remove it from the project or manually edit the module file and change the method moduleConfig() to return false.

Watch this video for an overview of the installation and setup of the code:

Initialization

The Tealium instance must be configured with the following parameters:

• account - the name of your iQ account
• profile - the name of the mobile profile within your iQ account
• environment - one of "qa", or "prod"
• datasource - (optional) data source key from UDH

// Minimum setup
var config = TealiumConfig(account: "your_account", 
                           profile: "your_profile", 
                       environment: "prod")

let tealium = Tealium(config:  config)

// With Datasource module (default included with framework builds)
var configWithDatasource = TealiumConfig(account: "your_account",
                                         profile: "your_profile",
                                     environment: "prod",
                                      datasource: "abc123")

let tealiumWithDatasource = Tealium(config: configWithDatasource)

Tracking

All tracking is done with the track() method, which takes the following parameters:

• title - (required) the name of the screen view or event to be tracked
• data - a dictionary object of tracking data
• type - the type of tracking call, as defined by the TealiumTrackType constants:
  •  TealiumTrackType.view - for tracking screen views
  •  TealiumTrackType.activity - (default) for tracking non-view user events
• completion - a closure to be run upon completion of the tracking call

The Collect submodule must be added to enable tracking calls.

// Basic track call
tealium.track(title:"someEvent",
               data:nil,
         completion:nil);

// With optional data
let data = [ "someKey" : "someValue" ]
tealium.track(title:"someEvent", 
               data:data, 
         completion:nil);

// With optional callback
tealium.track(title:"someEvent", 
               data: null,
         completion: { (success, info, error) in
    // Any monitoring or follow-up code here
})

// Specifying track type - ie appearance of a UIView
tealium.track(type:TealiumTrackType.view,
             title: "screenView",
              data: nil,
        completion: nil) 

Change Log

• 1.1 (current)
• 1.0.0-1.0.1