Adding Tealium to Your iOS App

Adding Tealium to Your iOS App

by Community Manager on ‎11-15-2016 01:27 PM - edited on ‎10-25-2018 06:10 AM by (14,198 Views)

This guide shows how to add Tealium to your iOS app to track user activity.

Table of Contents Placeholder

Requirements

  • Xcode 7 and higher
  • Compatible with iOS 8.1 and higher

For use with iQ Tag Management:

For use with Universal Data Hub:

Installing

CocoaPods

We recommend using CocoaPods CocoaPods to install the TealiumIOS framework. To do this, add the following dependency to your Podfile:

pod "TealiumIOS"

Save the file and run the following in your project directory:

pod install

Use the created .xcworkspace file to continue building your app. If you do not use the .xcworkspace file, you will not be able to build the app correctly.

Carthage

If you prefer, you may use Carthage to install the Tealium frameworks:

1. Add the following to your Cartfile

 binary "https://tags.tiqcdn.com/dle/tealiummobile/tealium-ios-carthage/tealium-carthage.json"

 2. Run  carthage update --platform ios  to download and extract the frameworks.

3. Make sure Carthage is properly integrated into your Xcode project, so that the required frameworks are copied automatically at build-time. 

3. Remember to strip simulator support as necessary before submitting to the App Store. You can avoid this step by using the "DeviceOnly" builds provided on the GitHub repo, which are also downloaded when using Carthage.

Add to Project Manually

You can also add Tealium to your project manually following these steps:

  1. Add TealiumIOS.framework to your project.
  2. Copy framework to project in the resulting dialog box.
  3. In the Target go to General > Embedded Binaries and add TealiumIOS.framework.

    For Swift projects go to the Build Settings > Swift Compiler > Objective-C Bridging Header option and include the file TealiumIOSBridgingHeader.h.

  4. Make sure all paths are as expected under Targets > Build Settings.

Initializing

The Tealium instance must be configured with the following parameters before it will begin tracking:

  • account - the name of your account
  • profile - the name of your profile
  • environment - one of "qa" or "prod"
  • datasource - (optional) the data source key from UDH
  • instance - a unique name for your instance (multiple instances are supported)

 In the Application Delegate or within a helper class setup method use the following initialization code:  

Swift

// set your account, profile, and environment
let tealConfig = TEALConfiguration.init(account: "ACCOUNT",
profile: "PROFILE",
environment: "prod",
datasource: "DATASOURCE") // Initialize with a unique key for this instance guard let tealium = Tealium.newInstanceForKey("INSTANCE", configuration: tealConfig) else { // Any additional failure response here return }

Objective-C

// import area
@import TealiumIOS;

// Set your account, profile, and environment
TEALConfiguration *tealConfig = [TEALConfiguration configurationWithAccount:@"YOUR_ACCOUNT"
                                                                    profile:@"YOUR_PROFILE"
                                                                environment:@"prod"
datasource:@"DATASOURCE"]; // Initialize with a unique key for this instance Tealium *tealium = [Tealium newInstanceForKey:@"INSTANCE" configuration:tealConfig]; 

The log level is set by default from the publish settings from your iQ account. To overriide this setting set the logLevel property in the TEALConfiguration instance:

Swift

// Set the log verbosity to errors only
tealConfig.logLevel = .prod

Objective-C

// Set the log verbosity to maximum
[tealConfig setLogLevel: TEALLogLevelDev];

Tracking Views

Every time a user opens or changes a screen in the app a tracking call should be made. This is easily done in the viewDidAppear method of any View Controller. A view is tracked by calling trackViewWithTitle() with two parameters: the name of the screen and (optionally) contextual view data. 

The screen name value will be populated in the event attribute named screen_title.

Swift

// Retrieve instance
let tealium = Tealium.newInstanceForKey("INSTANCE")

// Basic tealium?.trackViewWithTitle("screenName", dataSources: [:]) // With optional data let optionalData = ["someKey":"someValue"] tealium?.trackViewWithTitle("screenName", dataSources: optionalData) // With optional data let optionalData = ["someKey":["arrayValue1","arrayValue2"]] tealium?.trackViewWithTitle("screenName", dataSources: optionalData)

Objective-C

// Retrieve instance
Tealium *tealium = [Tealium instanceForKey:@"INSTANCE"];

// Basic [tealium trackViewWithTitle:@"screenName" dataSources:nil]; // With optional data NSDictionary *optionalData = @{@"someKey":@"someValue"}; [tealium trackViewWithTitle:@"screenName" dataSources: optionalData]; // With optional array data NSDictionary *optionalData = @{@"someKey":@[@"arrayValue1","arrayValue2"]}; [tealium trackViewWithTitle:@"screenName" dataSources: optionalData];

Tracking Events

All non-view activity should be tracked as an event. This is done by calling trackEventWithTitle() with two parameters: an event name and (optionally) contextual event data.

The event name value will be populated in the event attribute named tealium_event.

Swift

// Retrieve instance
let tealium = Tealium.newInstanceForKey("INSTANCE")

// Basic tealium?.trackEventWithTitle("someEvent", dataSources: [:]) // With optional data let optionalData = ["someKey":"someValue"] tealium?.trackEventWithTitle("someEvent", dataSources:optionalData) // With optional array data let optionalData = ["someKey": ["arrayValue1", "arrayValue2"]] tealium?.trackEventWithTitle("someEvent", dataSources:optionalData)

Objective-C

// Retrieve instance
Tealium *tealium = [Tealium instanceForKey:@"INSTANCE"];

// Basic [tealium trackEventWithTitle:@"someEvent" dataSources:nil]; // With optional data NSDictionary *optionalData = @{@"someKey":@"someValue"}; [tealium trackEventWithTitle:@"someEvent" dataSources:optionalData]; // With optional array data NSDictionary *optionalData = @{@"someKey":@[@"arrayValue1", @"arrayValue2"]}; [tealium trackEventWithTitle:@"someEvent" dataSources:optionalData];

Samples & Documentation 

Submitting to the App Store

The mobile library contains slices which will permit running it in the simulator. Unfortunately, the simulator architecture is not allowed by Apple when submitting to the App Store.  When creating your archive be sure to run one of the following two scripts to strip out the simulator:

 

Change Log

See GitHub