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:
- Add
TealiumIOS.framework to your project.
- Copy framework to project in the resulting dialog box.
- 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.
- 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
