Tealium Learning Center

Purpose Adds the user-resettable advertising identifier (IDFA) to each tracking call and optionally implements the Apple Search Ads API to gather attribution information (see [[external]: Apple Search Ads](https://searchads.apple.com/v/advanced/help/pdf/attribution-api.pdf for details)). Supported Platforms iOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumAttribution' Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . No additional import statements necessary. TealiumAttribution.framework External Dependencies UIKit, AdSupport, iAd Recommended Usage Usage of this module is optional. Please take the time to read about its functionality and decide if you really need it, as it introduces additional dependencies. Additionally, you will be required to explain to Apple why you are using IDFA when you submit your app. It should suffice to say that you are using it for attribution purposes. If you do not state that you are using IDFA, Apple will reject your app (see [external]: IDFA Usage). If you choose to exclude the module, the variables listed below will not be included in tracking calls. Included Variables The following variables will be transmitted with each tracking call while the module is enabled: Variable Name Description Example Value device_advertising_id User-resettable advertising identifier (IDFA) 6D92078A-8246-4BA4-AE5B-76104861E7DC device_advertising_vendor_id Unique ID guaranteed to be the same across all apps on the same device from a single vendor (apps with the same 1st 2 parts of the RDNS bundle identifier e.g. com.tealium or com.acme) 6D92078A-8246-4BA4-AE5B-76104861E7DC device_advertising_enabled Boolean to indicate whether the user has allowed ad tracking. True if ad tracking enabled, otherwise false. Note: if false, the advertising ID will appear as a string of zeroes true ad_user_clicked_last_30_days* True if user clicked on a Search Ads impression within 30 days prior to app download. true ad_user_date_clicked* Date and time the user clicked on a corresponding ad 2016-12-05T17:31:40Z ad_user_date_converted* Date and time the user downloaded your app 2016-12-05T17:31:40Z ad_org_name* The organization that owns the campaign the corresponding ad was part of. OrgName ad_campaign_id* The ID of the campaign the corresponding ad was part of 1234567890 ad_campaign_name* The name of the campaign the corresponding ad was part of CampaignName ad_group_id* The ID of the ad group the corresponding ad was part of 1234567890 ad_group_name* The name of the ad group the corresponding ad was part of. AdGroupName ad_keyword* The keyword that drove the ad impression which led to the corresponding ad click. Keyword * Note: these variables are only enabled if Search Ads has been explicitly enabled in the TealiumConfig object. These variables will only be retrieved from Apple's servers once during the app's lifetime, but they will be stored as persistent variables so they are available on future app launches. Future Improvements Update IDFA functionality to have a more robust retry mechanism if IDFA retrieval fails the first time (documented Apple limitation). Change Log 1.6.5 No functional changes. Minor code change to import TealiumCore module for Carthage builds. Removed unnecessary code for Swift versions <4.0 (no longer supported due to Xcode deprecation of Swift 3). 1.4.0 "device_advertising_id" has been changed from Identifier for Vendor (IDFV) to Identifier for Advertisers (IDFA). A new variable "device_advertising_vendor_id" has been added, which contains the IDFV. Added support for Apple Search Ads API. If this module is implemented, Tealium will collect attribution information from the Apple Search Ads API. ... View more

Swift is Apple's newest programming language, designed as a replacement for Objective-C, which was originally the main programming language available across all Apple's platforms (iOS, tvOS, watchOS, macOS). Swift brings a host of improvements and is designed from the ground up to be a safer environment in which to write apps, resulting in better-performing and more robust code, and a better end-user experience. App vendors are increasingly migrating to Swift to take advantage of these new features. To simplify using Tealium with Swift, we have created a new library to make it as easy as possible to implement our products in your Swift apps. Swift and Objective-C code can peacefully co-exist and is fully interoperable within the same app, making migration relatively easy. In this article: Table of Contents Placeholder Which Library Should I Use? The Tealium Swift library is fully compatible with apps running pure Swift, Objective-C, or any combination of the two. Since it is the newest and most up-to-date library, we strongly recommend implementing the Swift library if possible. The Objective-C library is still fully supported, but the Swift library will generally be updated faster and have the newest features.  Swift a dditionally  has the widest compatibility of all Tealium libraries, and can even support server-side Swift environments. There are some differences between the two libraries. Check the feature comparison table below to decide which one is most suitable to your needs. Memory Footprint and Performance All SDKs will in some way impact the performance and/or memory of your app, which will vary between apps, It can be difficult to measure the exact footprint of a specific SDK. Tealium has measured the Tealium Swift SDK against a baseline of a standard blank iOS Single View apps. These figures may vary for your specific implementation, so use them only as a rough indicator. The following  figures were obtained using the Xcode Allocations Instrument: Compiled App Archive (.ipa file) + 3MB Includes all available optional and mandatory/recommended modules Runtime Memory Usage +2 - +2.5MB Collect dispatcher + all other optional/recommended modules +7 - +10MB Tag Management dispatcher (UIWebView) + Collect dispatcher + all other optional/recommended modules Startup Time Approximate time from initialization to completion callback firing is ≈ 0.05 seconds. Which Swift Versions Are Supported? 4.0 and above (Xcode 9.0+) Which Operating System Versions Are Supported? iOS 9.0+ tvOS 9.2+ macOS 10.11+ WatchOS 3.0+ Which Tealium Products Are Supported? Tealium iQ Tag Management Tealium EventStream Tealium AudienceStream Tealium DataAccess Feature Comparison - tealium-swift vs. tealium-ios The Swift library was built from scratch using a completely new codebase to the Objective-C library (https://github.com/Tealium/tealium-ios). There are subtle differences between the two libraries in terms of the current feature set. The following table compares the features of both libraries. If you have requests for new features, you can open an issue on our GitHub page, or contact your account manager. Feature TealiumIOS (Objective-C) Tealium-Swift Description Notes Instance Manager/Multiton X X Enables support for multiple Tealium instances (profiles) running in the same app. May be added to Swift in a future release. Not a widely-used feature of the Objective-C library. Most customers do not need this feature. Auto Tracking / X Automatically tracks UIViews and Events Present in Swift, but will not be added to Objective-C Lifecycle Tracking X X Tracks App lifecycle events. N/A  Tag Management X X Allows use of Tealium iQ through a non-rendered web view N/A  Tealium Collect X X Sends data to Tealium's UDH using a native HTTPS request N/A  Offline functionality/queuing X X Automatically queues events if the device is online, and transmits when the device is online again In the iOS (Objective-C) library, queued events were persisted across app launches. This feature will be added to Swift in the next release. Current functionality is that any queued data is lost when the app is closed (swiped away) by the user. Remote Mobile Publish Settings (MPS) X / Allows remote configuration of certain library settings Planned support in a future release. Current method of configuration is by the TealiumConfig object only, and must be set at compile time. Volatile Data X X Stores data for the current session (until app is terminated) N/A  Persistent Data X X Stores data between app launches N/A  Remote Commands X X Allows triggering of specified native code blocks from Tealium iQ N/A    Apple Search Ads Support / X Adds support for the Apple Search Ads API to collect attribution data automatically Not planning to port to Objective-C Optimizely Experiment Tracking X / Tracks Optimizely experiment data automatically May port to Swift in future. iOS Support X X   N/A  watchOS Support X X   N/A  tvOS Support X X   N/A  macOS Support / X   N/A  CocoaPods Support X X Support for the CocoaPods dependency manager N/A    Carthage Support X X Support for the Carthage dependency manager N/A    Source Code Available / X May assist with debugging N/A  Consent Manager X X Assists with GDPR/privacy compliance N/A  X = Present —  / = Not Available —  P = Partial Support, see Notes column Variable Comparison - tealium-swift vs. tealium-ios See Swift: Variables List for a list comparing the differences between Swift and Objective-C variables. ... View more

Purpose Dispatches tracking calls to Tealium's Universal Data Hub (UDH). In the Objective-C library (GitHub:tealium-ios), the Collect module dispatched events to the main profile by default, unless overridden. By contrast, the Swift Collect module sends data to the profile passed in the TealiumConfig object. Supported Platforms iOS tvOS watchOS macOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumCollect Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . No additional import statements necessary. TealiumCollect.framework Recommended Usage Usage of this module is strongly recommended if you are using Tealium's UDH. As an alternative, if you are using the Tag Management module, you may instead use the Collect tag via Tealium iQ. This may give greater control over the data and events dispatched to the UDH, as you may then use load rules and extensions to manipulate the data prior to dispatch. If you are using the Collect tag via Tealium iQ, please ensure the Collect module is disabled to avoid duplicate tracking requests. Included Variables The following variables will be transmitted with each tracking call while the module is enabled: Variable Description Example Value dispatch_service Static string to indicate which module the tracking call came from collect Public API There are no public API methods for the Collect module. Dispatch successes and failures may be monitored through the Delegate module. Future Improvements No planned changes. Change Log 1.6.5 Minor code change to import TealiumCore module for Carthage builds. Switch to POST request by default. Added TealiumConfig method to switch back to legacy "vdata" dispatch method. Improved URL override methods to give greater flexibility. 1.4.0 Added config method to override collect URL Build 1 Send dispatches to vdata endpoint ... View more

Purpose Allows data variables to be stored on disk, and automatically adds them to each dispatch/tracking call. Please note, this module cannot be used on its own; it can only be used in conjunction with either the File Storage or DefaultsStorage module. Supported Platforms iOS tvOS watchOS macOS Installation The PersistentData module is bundled with both the FileStorage and DefaultsStorage modules. You should choose one of these modules only. CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumFileStorage OR pod 'tealium-swift/TealiumDefaultsStorage as required Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . TealiumFileStorage.framework OR TealiumDefaultsStorage.framework import TealiumFileStorage OR import TealiumDefaultsStorage // required if you need to store persistent data Recommended Usage Usage of this module is recommended. Included Variables No additional variables are introduced by this module. Public API add Adds variables to the persistent data store add(data:[String:Any]) Parameters Description Example Value data Dictionary of key/value pairs to add to persistent data ["somekey": "somevalue"] // SAMPLE // assuming 'tealium' initialized earlier tealium?.persistentData()?.add(data: ["customer_id":"1234567890-a"]) getData Adds variables to the persistent data store getData() // SAMPLE // assuming 'tealium' initialized earlier let data = tealium?.persistentData()?.getData() deleteData Deletes data for a specific set of known keys from the persistent data store deleteData(forKeys:[String]) Parameters Description Example Value forKeys [String] array of keys to delete. ["somekey", "someotherkey"] // SAMPLE // assuming 'tealium' initialized earlier tealium?.persistentData()?.deleteDate(forKeys: ["customer_id"]) deleteAllData Deletes all data in the persistent data store deleteAllData() // SAMPLE // assuming 'tealium' initialized earlier tealium?.persistentData()?.deleteAllData() Future Improvements No planned changes Change Log 1.6.5 Now bundled by default with DefaultsStorage and FileStorage modules Bug fix for potential memory leak Build 1 Initial release ... View more

The Tealium Swift library is designed around a modular architecture. Modules instantiate themselves automatically if they are present, and retrieve their configuration from the TealiumConfig object you create at initialization time. Disabling unneeded modules TealiumConfig method Before version 1.6.5 of the Tealium Swift SDK, the only way to disable unneeded modules if you were using CocoaPods or Carthage was via the TealiumConfig object, by setting an array of enabled/disabled modules (whitelist/blacklist). In this scenario, all the code was still compiled into your final app bundle, but any disabled modules were deactivated. This method is still supported, but we recommend migrating to one of the other methods below to take advantage of the performance gains associated with compiling less code into your app bundle. You can safely leave the module list enabled on the TealiumConfig object, and simultaneously remove unneeded modules. In the case where you attempt to enable a module, but the code is not present in your app bundle, it will not cause any undesired consequences, but will simply have no effect. Manual install from source code If you are installing the library manually, you may completely remove unneeded/unwanted modules from your project, and they will not be invoked. Carthage When you install with Carthage, you must explicitly import the modules you require. You may import all modules if you prefer, and use the module list, as described above, but your app will be lighter if you only import the modules you need. See Install with Carthage for instructions on including/excluding specific modules. CocoaPods See Install with CocoaPods for instructions on including/excluding specific modules. Module Dependencies All modules have a dependency on TealiumCore. This means installing any of the optional modules would also install TealiumCore automatically. Module List The modules are listed below in priority order (the internal order in which auto-instantiation takes place). Where additional documentation is required/available, this is linked from the module name in the table. Module Name ID Module Priority (Load Order) Module Group Description Supported Platforms Usage Notes ConsentManager consentmanager 50 - Aids GDPR/privacy compliance iOS, macOS, tvOS, watchOS Recommended   Logger logger 100 - Debug logging iOS, macOS, tvOS, watchOs Recommended - Lifecycle lifecycle 175 - Tracks launches, wakes, sleeps, and crash instances. Auto or manually. iOS, tvOS, watchOS Recommended - Autotracking autotracking 300 - Prepares & sends dispatches for most UI, including viewDidAppear, events. iOS, tvOS Not Recommended* - FileStorage filestorage 350 Persistent Storage Adds general persistence capability for any module. Replaces the Defaults Storage module. Backed by NSKeyedArchiver iOS, macOS, watchOS, tvOS Recommended*   DefaultsStorage defaultsstorage 360 Persistent Storage Adds general persistence capability for any module. Backed by UserDefaults iOS, tvOS, watchOS, macOS Recommended*   Attribution attribution 400 - Adds IDFA to track data. iOS Optional Requires additional entitlements from Apple. Manual import option only. AppData appdata 500 - Adds app_uuid to track data. iOS, macOS, tvOS, watchOS Recommended - Datasource datasource 550 - Adds an additional config init option for datasource ids. iOS, macOS, tvOS, watchOS Recommended - DeviceData devicedata 525 - Add as additional device info to all track data. iOS Recommended - PersistentData persistentdata 600 - Adds ability to add persistent data to all track data. iOS, macOS, tvOS, watchOS Recommended - Volatile Data volatiledata 700 - Adds ability to add session persistent data to all track data - clears upon app termination/close. iOS, macOS, tvOS, watchOS Recommended Will supersede any Persistent value with the same key(s) Delegate delegate 900 - Adds multicast delegates to monitor or suppress track dispatches. iOS, macOS, tvOS, watchOS Optional - Connectivity connectivity 950 - Adds ability to flag track messages for delayed delivery due to connectivity loss. iOS, macOS, tvOS Recommended Requires SystemConfiguration DispatchQueue dispatchqueue 1000 - Adds persistent storage for queued dispatches iOS, macOS, tvOS, watchOS Recommended - Collect collect 1000 Dispatchers Packages and delivers track call to Tealium Collect or other custom URL endpoint. iOS, macOS, tvOS, watchOS Optional* - TagManagement tagmanagement 1100 Dispatchers UIWebview based dispatch service that permits library to run TIQ/utag.js. iOS Optional* Requires UIWebView RemoteCommands remotecommands 1200 - Permits configurable remote code block execution via URLScheme, UIWebView, or TagManagement. iOS Optional* - * Please read documentation for full details. Where a module is listed as optional, and it has a "module group" listed, one or both modules of the same module group is required to fulfil the library's tracking requirements. For example, Collect and Tag Management are in the "Dispatchers" group, and you need at least one of these enabled for any data to be sent. Likewise with the Persistent Storage group; you need one or the other to be enabled, or you will not get any persistent storage options. Recommended Default Modules Please speak to your account manager if you are unsure which products you are licensed for These are recommended default modules for most implementations. You are free to add/remove modules as needed. Option 1: If using Tealium iQ (Tag Management) only Core Attribution AppData Connectivity Consent Manager DataSource Delegate DeviceData DispatchQueue FileStorage Lifecycle Logger PersistentData RemoteCommands TagManagement VolatileData Option 2: If using Tealium UDH (Collect) only Core Attribution AppData Collect Connectivity Consent Manager DataSource Delegate DeviceData DispatchQueue FileStorage Lifecycle Logger PersistentData VolatileData Option 3: If using Tealium UDH and Tealium iQ together Please see Collect documentation to decide whether Collect module is actually required. Core Attribution AppData Collect Connectivity Consent Manager DataSource Delegate DeviceData DispatchQueue FileStorage Lifecycle Logger PersistentData RemoteCommands TagManagement VolatileData ... View more

Tag Management/Tealium iQ Enables remote configuration of JavaScript-based tags using Tealium iQ. All libraries supporting this feature implement a non-rendered web view to act as a host for the JavaScript tags. Data from tags is sent directly from the device to the tag vendor's server (e.g. Adobe, Criteo, Google). In order to use this feature, it must have been explicitly enabled in the remote publish settings (see https://community.tealiumiq.com/t5/Mobile-Libraries/Mobile-Publish-Settings/ta-p/13633), or in the case of the Swift library, it must be enabled in the native code when Tealium is initialized. If the Tag Management feature is disabled, the non-rendered web view will not be created, although the Android and iOS (Objective-C) libraries will still make a request for the "mobile.html" file, solely for the purposes of downloading the Mobile Publish Settings. This request comes from native code, and does not involve the web view. Tealium Collect/UDH Enables support for Tealium's Universal Data Hub (UDH) suite of products. When enabled, an HTTPS request will be sent directly to Tealium's servers for processing for each tracking call implemented in your app. This single HTTPS request can be used to power one or more of the following products simultaneously: AudienceStream EventStore AudienceDB & EventDB EventStream If you are not licensed for one of these products, you should disable the Tealium Collect service in your app, which can be done through the remote publish settings. For Swift, you will need to make sure the module is disabled, as it does not currently utilize the remote publish settings feature. This feature may be used in conjunction with the Tag Management feature, but please ensure that you do not also have the Collect Tag set up through Tealium iQ, as this will lead to double-counting (1 hit from the native Collect service, and one from the Tealium iQ Collect tag). Collect Tag vs. Native Collect Module If you are already using Tealium iQ in your app, then using the Collect tag offers some advantages over the native Collect module. The main benefit is that you have the ability to manipulate data using Extensions in Tealium iQ before the data is transmitted to the UDH. You can also use load rules to filter which events are sent to the UDH. If you are using the native Collect module, all events are sent to the UDH, and there are no options to manipulate the data, apart from by using enrichments in the UDH. If, however, you do not need to use Tealium iQ for tag delivery (e.g. you are using EventStream to deliver your data to third party tag vendors), then the Collect module offers some advantages; exclusively using the Collect module and disabling Tag Management will result in fewer HTTP(s) requests being made from the app, since instead of sending data to multiple vendors directly from the device, only a single request is sent to Tealium per tracking call implemented in the app. This may help to reduce battery and data consumption, resulting in a better experience for your end-users. Additionally, if you are using AudienceStream, the native module offers built-in Data Layer Enrichment (DLE) callbacks which can be used to personalize your app based on known visitor attributes (e.g. high value customers could receive additional features or promotions, based on the cross-device data Tealium holds in AudienceStream). If you implement the Collect tag through Tealium iQ, DLE will still function as expected, but visitor attributes will only be available at the JavaScript-level inside the non-rendered web view. Remote Commands Remote Commands (also known as Custom Remote Commands/Dynamic Triggers) provide the ability to trigger native code blocks from within the Tealium iQ non-rendered web view. For this reason, they can only be used if you have implemented/enabled the Tag Management feature/module in your app. Only remote commands that have been explicitly enabled will be able to run (there is no way for Tealium iQ to execute arbitrary code on the device). This feature is primarily used for cases where data held inside the non-rendered web view needs to be passed back to the native code for further processing (e.g. you may need to access a value stored in a cookie or localStorage inside the Tealium iQ web view). Another use for this feature would be to personalise parts of your app, for example, you may wish to trigger a survey in the app once the user has been through a particular journey, such as making a purchase. The flow for this particular example would be: Create some generic native code capable of triggering a local notification on the device, which prompts the user to take a survey. Register this block of code as a Remote Command with the Tealium API (See Links). In Tealium iQ, create a new "Custom Remote Command" tag, and make sure the command ID matches the command ID you used to register the command in the native code. Mappings can be set up to pass specific data variables back to the app, for example, you might wish to pass a customized survey message back to the app, e.g. "Thank you for making a purchase. Would you mind taking a short survey?". You might also pass back a specific URL to open when the user clicks the notification, so that you can pass the user through to a specific web-hosted survey using your survey tool of choice. In the app, the native code should look for specific variables passed back in the response (e.g. "survey_url" and "survey_title"), display the message in the notification, and launch a web view or the native browser when the user clicks the notification. If you wish to change the survey URL, or the message displayed to the user, you can now control this through Tealium iQ extensions, without needing to re-deploy your app. You can also disable the survey at-will, or change the trigger that leads to the survey being displayed (e.g. display on the home screen instead of the order confirmation screen). There are many other potential uses for Remote Commands, including remote configuration of third party SDKs in your app. Speak to your account manager/deployment engineer if you have any questions. Lifecycle Tracking Each platform has its own Lifecycle module, which enables automatic tracking of app lifeycle events (launch, wake, sleep) and associated data. Mobile Publish Settings (MPS) Mobile Publish Settings allow you to remotely control some aspects of the Tealium SDKs' functionality, without needing to deploy an app update. You can read full details in this article: https://community.tealiumiq.com/t5/Mobile-Libraries/Mobile-Publish-Settings/ta-p/13633 Storage In addition to passing specific data layer variables with each tracking call, some variables need to remain consistent throughout your app's lifecycle. Instead of manually sending these variables with every request, you can use one of our storage APIs to automatically add the data to each request. Volatile Storage Items added to volatile storage are kept until the app is cleared from memory (i.e. force-closed/restarted). From the point you set a volatile data variable, it will be sent on every subsequent request automatically until it is cleared. Volatile data is not stored on disk, so will not contribute to the app's disk usage footprint on the device. Persistent Storage Items added to persistent storage are kept for the lifetime of the app (until the user uninstalls the app or manually clears the app's data), or until you clear the variable via the API. Like volatile variables, persistent variables are sent with every tracking call until they are cleared. An example of a variable you might like to keep in persistent storage is a visitor id, such as a user's email address. Links RemoteCommands on tealium-ios RemoteCommands on tealium-swift RemoteCommands on tealium-android General Documentation - Swift General Documentation - Objective-C General Documentation - Android ... View more

Purpose Enables logging of debug information to the LLDB console. Supported Platforms iOS tvOS watchOS macOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumLogger Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . No additional import statements necessary. TealiumLogger.framework Recommended Usage Usage of this module is recommended. If you do not enable it, you will not see any logging from the Tealium library. Included Variables No new variables are introduced by this module. Public API There are no public API methods for this module. The module can be controlled by using the settings available in the TealiumConfig object. Available Log Levels Log Level Description Enum value None Logging disabled TealiumLogLevelValue.none Errors Only errors will be reported TealiumLogLevelValue.errors Warnings Only errors and warnings will be reported TealiumLogLevelValue.warnings Verbose All log output will be reported, including an entry for each tracking call/dispatch TealiumLogLevelValue.verbose Future Improvements Additional logging to be added for all modules. Change Log Build 1.4.0 Improved logging for Persistent Data ... View more

Purpose Adds the UDH-generated data source variable to each dispatch. Supported Platforms iOS tvOS watchOS macOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumDataSource Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . TealiumDataSource.framework import TealiumDataSource // allows datasource param to be set on the TealiumConfig class instance Recommended Usage Usage of this module is recommended if you are using the UDH. You can generate a data source key via the UDH user interface. If you are using Tag Management only, it currently doesn't have any effect, apart from adding a new variable to each dispatch. See the Data Sources documentation for more information on this feature. Included Variables The following variables will be transmitted with each tracking call while the module is enabled: Variable Name Description Example Value tealium_datasource Specifies the data source name. Added to every dispatch. abc123 Public API No public API methods available. The Data Source variable can be set via the TealiumConfig object (see Swift Class: TealiumConfig) Future Improvements No planned changes Change Log Build 1 Initial release ... View more

Basic Concepts This document covers all the basics to get you up and running with Tealium as quickly as possible. In most cases, the API calls described here are all you will ever need to implement, unless you want to use some of the more advanced features of the library, which are covered in separate documents (see Modules Documentation). Tracking Calls The Tealium tracking API provided by the Swift library is designed to capture two types of events: Screen Views In general, we advise that every screen in your app is tracked (usually in viewDidAppear or similar), and any other relevant variables should be passed in a Dictionary in the data parameter. User Interation Events (e.g. Button Clicks) You should add track calls for significant events in your app, e.g. a call-to-action button, "Buy Now", "Add To Cart". Adding more tracking calls upfront, before the app is deployed to the App Store, will reduce the need to add more tracking at a future date, and reduce the need for app updates. If in doubt, track it; tracking calls can be filtered out/ignored if not needed later on, but they are more tricky to add to your app later. Helper Class We recommend the use of a helper class to abstract the Tealium API implementation from the rest of your app. This will give you a single entry point from which to call Tealium, and in the event that we make breaking changes in future releases (we always try not to!), you only need to update the code in your helper file, and not in every single ViewController or Swift file. A sample helper class is provided in the GitHub repo. Sample Code Initialization/Instantiation This code should generally be run as part of your helper class to initialize Tealium for the first time. // REQUIRED Config object for lib let config = TealiumConfig(account: "tealiummobile", profile: "demo", environment: "dev", datasource: "test12", optionalData: nil) // OPTIONALLY set log level config.setLogLevel(logLevel: .verbose) // REQUIRED Initialization - recommend making tealium reference a member of your singleton helper; it should only be instantiated once let tealium = Tealium(config: config) { // Optional processing post init. } Modules The Tealium Swift library is modular. This means you only need to install the specific components you need, and any you don't need are excluded from your build. This saves resources while your app is running, and makes sure your end users get the best possible experience. See https://community.tealiumiq.com/t5/Tealium-for-Swift/x/ta-p/20533 for recommended module lists. Track Screen Views This code block will track a screen view on the homescreen, passing a Dictionary containing two key-value pairs, the first representing the customer id, and the second, an array of product IDs purchased in this transaction (in this instance, containing 1 product only). You may optionally specify a completion block, but you may pass nil if you don't need special completion handling. // assuming 'tealium' has already been instantiated tealium?.trackView(title: "Buy Now", data: ["customer_id" : "1234567890-a", "product_ids" : ["widget123"]], completion: nil) Track User Events This code block will track a button click on "Buy Now", passing a Dictionary containing a single key-value pair, representing the customer id. You may optionally specify a completion block, but you may pass nil if you don't need special completion handling. // assuming 'tealium' has already been instantiated tealium?.track(title: "Homescreen", data: ["customer_id" : "1234567890-a"], completion: nil) Add Persistent Data Persistent data storage should be used for those variables which rarely change during the app's lifecycle, but are required to be sent on every tracking call. An example of this may be a customer ID that stays the same until the user logs out. Persistent data remains set across multiple app launches (since it is stored on disk), and can only be modified by deleting the data through the persistent data API, or overwriting an existing key with a new value. Persistent data is merged with any dictionary passed in each tracking call ( trackView or track ), and sent to any enabled dispatch services. NOTE: Persistent Data storage is backed by either UserDefaults or File Storage, depending on the modules currently enabled. tealium?.persistentData()?.add(data: ["customer_id":"1234567890-a"]) Add Volatile Data Volatile data storage should be used for those variables that do not change during a single launch of the app, but may change for future launches. An example of this may be some sort of session ID, which is regenerated each time the user relaunches the app. Volatile data works in a similar way to persistent data, except that it is only kept in main memory, and never written to disk. Thus, force closing an app will clear all volatile data previously set. From the point it is set, volatile data will be sent on each subsequent tracking call, and its data merged with any Dictionary passed in to the tracking call. tealium?.volatileData()?.add(data: ["session_id":"1234567890232"])   ... View more

General Information The full source code for the Swift Library is available on GitHub, and, as such, you can manually install the library by simply copying the required code into your Xcode project Integration Steps 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 you should also implement either the TagManagement or Collect module in order for dispatches to be sent. If no dispatch modules are added, the app will not transmit any data. Please see Modules List for further information on the available modules. ... View more

Purpose Gathers important information about the app bundle. Supported Platforms iOS macOS watchOS tvOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumAppData' Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . No additional import statements necessary. TealiumAppData.framework Recommended Usage Usage of this module is recommended, but not mandatory. If you choose to exclude it, the variables listed below will not be included in tracking calls. Included Variables The following variables will be transmitted with each tracking call while the module is enabled: Variable Name Description Example Value app_build Minor build version of the app 2213 app_name Name of the app (usually same as App Store name) Digital Velocity app_rdns Fully-qualified name of the app bundle com.tealium.digitalvelocity app_uuid Random uuid. Persists for the duration of the app install, so long as one of the persistent storage modules is also enabled. Resets if app is uninstalled. 123e4567-e89b-12d3-a456-426655440000 app_version Version of the app bundle 1.0 tealium_visitor_id Persistent Tealium visitor ID 123e4567e89b12d3a456426655440000 Future Improvements No planned changes Change Log 1.6.5 No functional changes. Minor code change to import TealiumCore module for Carthage builds. 1.4.0 Removed deprecated "tealium_vid" variable ... View more

General Information Carthage is a popular decentralized dependency manager for the various Apple platforms (iOS, tvOS, watchOS, macOS). You can find out more about Carthage here: https://github.com/Carthage/Carthage Installing Carthage You can install Carthage manually or using Homebrew (recommended). If using Homebrew, you can install Carthage with the following command: brew install carthage Integration Steps Add the following entry to your Cartfile: github "tealium/tealium-swift" Run carthage update in your terminal window, which 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 --cache-builds ( --cache-builds will speed up subsequent builds after the initial build) Drag the frameworks you require into your Xcode project's General > Embedded Binaries section. *see note below Be sure to 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. Make sure the Tealium frameworks have been added to the Embedded Binaries section in your project settings, otherwise your app will crash at launch. * Modularization: 1.6.5 As of version 1.6.5, 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. Due to some current limitations in Carthage, we had to choose between the convenience of importing the entire SDK in one go, and the flexibility and performance gains of a fully modular install. The downside to this is that it's now necessary to add each module you wish to use individually. Carthage will build all the modules and output the resulting .framework files into your Carthage build directory, but you can delete any modules you don't need, and just drag into Xcode those that you do need. See Modules for further details on recommended module lists. Module Import Statements import TealiumCore // required for Tealium, TealiumConfig, TealiumInstanceManager import TealiumVolatileData // required if you wish to store volatile data through the Volatile Data API import TealiumFileStorage OR import TealiumDefaultsStorage // required if you need to store persistent data import TealiumRemoteCommands // required if you need to interact with the Remote Commands API import TealiumDelegate // required if you need to set up a tracking delegate import TealiumDataSource // allows datasource param to be set on the TealiumConfig class instance import TealiumLifecycle // only required if you need to manually call the Lifecycle API ... View more

Purpose Allows data variables to be stored in main memory (RAM). Data will be stored and added to all dispatches/tracking calls until the app is restarted. Supported Platforms iOS tvOS watchOS macOS Installation CocoaPods Framework will be auto-instantiated, so long as the pod is installed. Depends on TealiumCore pod. No additional import statements necessary besides import TealiumSwift . pod 'tealium-swift/TealiumVolatileData Carthage Framework will be auto-instantiated, so long as it is compiled into your app (included in "Embedded Binaries"). Depends on TealiumCore . No additional import statements necessary. TealiumVolatileData.framework import TealiumVolatileData // required if you wish to store volatile data through the Volatile Data API Recommended Usage Usage of this module is mandatory. If you do not implement it, vital variables will be missing from tracking calls. Included Variables Variable Name Description Example Value Supported Platforms tealium_random Random number 8449989974958830 iOS, tvOS, watchOS, macOS tealium_session_id Tealium Session ID 1511262829677 iOS, tvOS, watchOS, macOS tealium_timestamp_epoch Current Unix timestamp (1970 epoch) in seconds 1511262829 iOS, tvOS, watchOS, macOS tealium_account Current Tealium account (from TealiumConfig object) tealium iOS, tvOS, watchOS, macOS tealium_profile Current Tealium profile (from TealiumConfig object) mobile iOS, tvOS, watchOS, macOS tealium_environment Current Tealium environment (from TealiumConfig object) dev iOS, tvOS, watchOS, macOS tealium_library_name Tealium library name swift iOS, tvOS, watchOS, macOS tealium_library_version Tealium library version 1.4.0 iOS, tvOS, watchOS, macOS event_timestamp_iso Event timestamp in ISO8601 (Zulu Time), UTC 2017-11-20T14:48:00Z iOS, tvOS, watchOS, macOS event_timestamp_local_iso Event timestamp in ISO8601 local timezone 2017-11-20T06:48:00 iOS, tvOS, watchOS, macOS event_timestamp_offset_hours Current offset from UTC in hours -8 iOS, tvOS, watchOS, macOS event_timestamp_unix_millis Current Unix timestamp (1970 epoch) in milliseconds 1511189280337 iOS, tvOS, watchOS, macOS event_timestamp_unix Current Unix timestamp (1970 epoch) in seconds 1511189280 iOS, tvOS, watchOS, macOS Public API Module methods are accessed through the Tealium class. add Adds variables to the volatile data store add(data:[String:Any]) Parameters Description Example Value data Dictionary of key/value pairs to add to volatile data ["somekey": "somevalue"] // SAMPLE // assuming 'tealium' initialized earlier tealium?.volatileData()?.add(data: ["customer_id":"1234567890-a"]) getData Returns all volatile data previously set with volatileData().add() getData() -> [String:Any] // SAMPLE // assuming 'tealium' initialized earlier let data = tealium?.volatileData()?.getData() deleteData Deletes data for a specific set of known keys from the volatile data store deleteData(forKeys:[String]) Parameters Description Example Value forKeys [String] array of keys to delete. ["somekey", "someotherkey"] // SAMPLE // assuming 'tealium' initialized earlier tealium?.volatileData()?.deleteData(forKeys:["customer_id"]) deleteAllData Deletes all data in the volatile data store deleteAllData() // SAMPLE // assuming 'tealium' initialized earlier tealium?.volatileData()?.deleteAllData() resetSessionId Reset the session id for current session. resetSessionId() // SAMPLE // assuming 'tealium' initialized earlier tealium?.volatileData()?.resetSessionId() setSessionId Override the existing session id for current session. setSessionId(sessionId: String) Parameters Description Example Value sessionId Override the session ID for the current session "someSessionId" // SAMPLE // assuming 'tealium' initialized earlier tealium?.volatileData()?.setSessionId(sessionId: "123456123456009") Future Improvements Improve logging for errors/info Change Log 1.6.5 Fixed bug causing timestamps from queued hits to be overwritten Added event_timestamp_unix , which is a second-precise 1970-epoch timestamp 1.4.0 Added new public method to remove all volatile data Added several different kinds of event timestamps for compatibility with Objective-C library Fixed tealium_timestamp_epoch variable to return an integer, rather than decimal/float ... View more

Table of Contents Placeholder AppData Module Variables The following variables are available in the AppData module. Variable Name Description app_build Minor build version of the app Example: 2213 app_name Name of the app (usually same as App Store name) Example: Digital Velocity app_rdns Fully-qualified name of the app bundle Example: com.tealium.digitalvelocity app_uuid Random uuid. Persists for the duration of the app install, so long as one of the persistent storage modules is also enabled. Resets if app is uninstalled. Example: 123e4567-e89b-12d3-a456-426655440000 app_version Version of the app bundle Example: 1.0 app_version_full App Version + Build Number Example: 1.0 (2213) tealium_vid Persistent Tealium visitor ID Example: 123e4567e89b12d3a456426655440000 tealium_visitor_id Same as tealium_vid. Included for legacy reasons Example: 123e4567e89b12d3a456426655440000 Attribution Module Variables The following variables are available in the Attribution module. Variable Name Description ad_campaign_id The ID of the campaign the corresponding ad was part of Example: 1234567890 ad_campaign_name The name of the campaign the corresponding ad was part of Example: CampaignName ad_group_id The ID of the ad group the corresponding ad was part of Example: 1234567890 ad_group_name The name of the ad group the corresponding ad was part of. Example: AdGroupName ad_keyword The keyword that drove the ad impression which led to the corresponding ad click. Example: Keyword ad_org_name The organization that owns the campaign the corresponding ad was part of. Example: OrgName ad_user_clicked_last_30_days True if user clicked on a Search Ads impression within 30 days prior to app download. Example: true ad_user_date_clicked Date and time the user clicked on a corresponding ad Example: 2016-12-05T17:31:40Z ad_user_date_converted Date and time the user downloaded your app Example: 2016-12-05T17:31:40Z device_advertising_id User-resettable advertising identifier (IDFA) Example: 6D92078A-8246-4BA4-AE5B-76104861E7DC device_advertising_enabled Boolean to indicate whether the user has allowed ad tracking. True if ad tracking enabled, otherwise false. Note: if false, the advertising ID will appear as a string of zeroes Example: true device_advertising_vendor_id Unique ID guaranteed to be the same across all apps on the same device from a single vendor (apps with the same 1st 2 parts of the RDNS bundle identifier e.g. com.tealium or com.acme) Example: 6D92078A-8246-4BA4-AE5B-76104861E7DC Autotracking Module Variables The following variables are available in the Autotracking module. Variable Name Description autotracked Set to true and added to each autotracked tracking call Example: true ConsentManager Module Variables The following variables are available in the ConsentManager module. Variable Name Description consent_categories An array of the user's selected consent categories Example: ["analytics", "cdp"] consent_status The user's current consent status Example: consented/notConsented policy Consent Policy Example: "gdpr" Connectivity Module Variables The following variables are available in the Connectivity module. Variable Name Description tealium_datasource Specifies the data source name. Added to every dispatch. Example: abc123 was_queued Indicates whether a tracking call was queued due to no connectivity. Only present for queued events; absent for all other events Example: true Core Module Variables The following variables are available in the VolatileData module. Variable Name Description screen_title Screen title passed to trackView call Example: "homescreen" tealium_event The name of the event being tracked Example: "checkout" Crash Reporter Module Variables Variable Name Description/Example crash_cause Cause of the crash Example: Crash Reason crash_name Friendly name of the crash, if available Example: Crash Name crash_libraries List of loaded libraries at the time of the crash Example: `[{"baseAddress": "0xa3e0000", "codeType": { "arch": 64, "typeEncoding": "Mach"}, "imageName": "/Applications/Xcode9.3.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/CoreSimulator/Profiles/Runtimes/iOS.simruntime/Contents/Resources/RuntimeRoot/usr/lib/dyld_sim", "imageSize": 212992, "imageUuid": "4015e9b70bde"}]`` crash_process_id PID of the app at time of crash Example: 84351 crash_process_path Path the app was running under Example: /DemoApp.app/DemoApp crash_parent_process Parent process that launched the app Example: launchd_sim crash_parent_process_id Example: Parent process PID 83183 crash_signal_address Signal address of the crash Example: 4572945982 crash_signal_code Signal code causing the crash Example: #0 crash_signal_name Signal name causing the crash Example: SIGABRT crash_threads Returns all active threads at the time of the crash Example: `{"crashed": 1,"registers": {"cs": "0x07"},"stack": {"instructionPointer": 4572945982,"symbolInfo": {"symbolName": "","symbolStartAddr": 0},"threadId": ""}}` crash_uuid Unique identifier for this specific crash Example: CC2DA0E9-E544-429A-AC5E-A268FC62F02A device_memory_usage Current memory used by the app on the device at the time of the crash Example: 143.57MB device_memory_available Free memory on device at the time of the crash Example: 1068.88MB device_os_build Current OS build number Example: 15E217 Datasource Module Variables The following variables are available in the Datasource module. Variable Name Description tealium_datasource Specifies the data source name. Added to every dispatch. Example: "a1b2c3" DeviceData Module Variables The following variables are available in the DeviceData module. Variable Name Description app_memory_usage Memory being used by the current process/app in Megabytes Example: 35.75MB battery_percent Current battery percentage at time of track call Example: 58 cpu_architecture CPU architecture Example: 64 cpu_type CPU type Example: ARM64v8 device_is_charging Boolean to indicate if device is currently charging at time of track call Example: false device_orientation Simple orientation Example: Portrait, Landscape device_orientation_extended Full orientation Example: Face Up device_resolution Screen resolution Example: 1080x1920 memory_active* Total active memory on the device Example: 997.78MB memory_compressed* Total compressed memory on the device Example: 153.39MB memory_free* Total free memory on the device Example: 120.81MB memory_inactive* Total inactive memory on the device Example: 441.83MB memory_physical* Total physical memory on the device (RAM) in Megabytes Example: 2013.50MB memory_wired* Total wired memory on the device Example: 207.12MB model_name Consumer device name Example: iPhone 7 Plus model_variant Model variant (generally indicates which radio technology is available on the device) Example: CDMA, GSM, WiFi, Cellular network_connection_type** Current connection type Example: wifi, cellular network_iso_country_code Mobile network ISO country code Example: gb network_mcc Mobile network Country Code (see https://en.wikipedia.org/wiki/Mobilecountrycode) Example: 234 network_mnc Mobile network code (see https://en.wikipedia.org/wiki/Mobilecountrycode) Example: 34 network_name Mobile network carrier name Example: EE os_build Operating System Build Version Example: 15J580 os_name Operating System Name Example: iOS, tvOS, watchOS, macOS os_version Operating system version Example: 11.1 user_locale Current device language Example: en Lifecycle Module Variables The following variables are available in the Lifecycle module. Variable Name Description lifecycle_dayofweek_local Local day of week that call was made - 1=Sunday, 2=Monday, etc.) Example: 4 lifecycle_dayssincelastwake Days since last detected wake in integer increments Example: 1 lifecycle_dayssincelaunch Days since first launch in integer increments Example: 23 lifecycle_dayssinceupdate Days since the last detected app version update in integer increments Example: 46 lifecycle_diddetect_crash Was a crash detected during this launch/wake event. Populated only if true. Example: true lifecycle_firstlaunchdate GMT timestamp of very first detected launch/wake in ISO8601 format from Zulu time Example: 2013-07-11T17:55:04Z lifecycle_firstlaunchdate_MMDDYYYY GMT Timestamp formatted as MM/DD/YYYY Example: 01/18/2012 lifecycle_hourofday_local Local hour of day that call was made (24 hour format) Example: true lifecycle_isfirstlaunch Only present if call is very first launch/wake call Example: true lifecycle_isfirstlaunchupdate Only present if call is first launch/wake after a detected updated Example: true lifecycle_isfirstwakemonth Only present if call is first launch/wake of the month Example: true lifecycle_isfirstwaketoday Only present if call is first launch/wake of the day Example: true lifecycle_launchcount Total number of launches this version of your app (since the last update) Example: 3 lifecycle_priorsecondsawake Whole seconds app was awake since last launch only. Aggregates total from all wakes prior. Sent only with lifecycle_type: launch calls. Example: 126 lifecycle_secondsawake Whole seconds app was awake since most recent wake/launch. Example: 30 lifecycle_sleepcount Total number of times your app has gone to sleep (resets if updated) Example: 5 lifecycle_totalcrashcount Total number of crashes counted since install (only reset if app deleted) Example: 21 lifecycle_totallaunchcount Total number of launches since install (only reset if app deleted) Example: 3 lifecycle_totalsecondsawake Total number of seconds your app has been in a woken/active state since app install (only reset if app deleted) Example: 36 lifecycle_totalsleepcount Total number of times your app has gone into the background since app install (only reset if app deleted) Example: "400" lifecycle_totalwakecount Total number of launches + wakes since install (only reset if app deleted) Example: "563" lifecycle_type Type of lifecycle call Example: "launch", "wake", "sleep" lifecycle_updatelaunchdate GMT timestamp of first wake/launch after a version update has been detected Example: 2014-09-08T18:10:01Z lifecycle_wakecount Total number of launches + wakes in this version of your app (resets if updated) Example: "29" TagManagement Module Variables The following variables are available in the TagManagement module. Variable Name Description dispatch_service Static string to indicate which module the tracking call came from Example: collect/tagmanagement VolatileData Module Variables The following variables are available in the VolatileData module. Variable Name Description event_timestamp_local_iso Event timestamp in ISO8601 local timezone Example: 2017-11-20T06:48:00 event_timestamp_iso Event timestamp in ISO8601 (Zulu Time), UTC Example: 2017-11-20T14:48:00Z event_timestamp_offset_hours Current offset from UTC in hours Example: -8 event_timestamp_unix Current Unix timestamp (1970 epoch) in seconds Example: 1511189280 event_timestamp_unix_millis Current Unix timestamp (1970 epoch) in milliseconds Example: 1511189280337 tealium_account Current Tealium account (from TealiumConfig object) Example: tealium tealium_environment Current Tealium environment (from TealiumConfig object) Example: dev tealium_library_name Tealium library name Example: swift tealium_library_version Tealium library version Example: 1.4.0 tealium_profile Current Tealium profile (from TealiumConfig object) Example: mobile tealium_random Random number Example: 8449989974958830 tealium_session_id Tealium Session ID Example: 1511262829677 tealium_timestamp_epoch Current Unix timestamp (1970 epoch) in seconds Example: 1511262829 ... View more