Tealium

Class: Tealium

The following summarizes the commonly used methods of the iOS (Swift) Tealium class.

cancelTimedEvent()

Cancels the timer for a timed event. The timed event is not tracked.

tealium?.cancelTimedEvent(name: "TIMED_EVENT_NAME")

clearAllTimedEvents()

Clears all previously started timed events. The timed events are not tracked.

tealium?.clearAllTimedEvents()

clearStoredVisitorIds()

Clears all previously stored visitor IDs and hashed customer identifiers.

tealium?.clearStoredVisitorIds()

decorateUrl()

Decorates the input URL with the Adobe ECID query parameters.

decorateUrl(_ url: URL, completion: ((URL) → Void)

Example:

var tealium: Tealium?
...
let url = URL(string: "https://www.tealium.com")!
tealium?.adobeVisitorApi?.decorateUrl(url) { newUrl in
    // use the new URL
}

disable()

Disables the Tealium library and removes all module references. Re-enable by creating a new Tealium instance if required.

tealium?.disable()

flushQueue()

Sends all queued dispatches immediately. Requests may still be blocked by DispatchValidators such as Consent Manager

tealium?.disable()

gatherTrackData()

Retrieves all the current custom data layer values and collector module data layer values. The results are cached for subsequent calls and returned asynchronously. Set retrieveCachedData to false to get the most recent values. Use the completion handler to process the returned values. Reference custom data layer values directly using their custom keys and reference collector module values using TealiumDataKey..

 tealium?.gatherTrackData(retreiveCachedData: false, completion: { allData in
    let lifecycleTotalWakeCount = allData[TealiumDataKey.totalWakeCount]
    let visitorId = allData[TealiumDataKey.visitorId]
    let userLanguage = allData["user_language"]
})

See also Tealium.dataLayer.all.

getTagManagementWebView()

(New in v2.10.0)

Returns the TagManagement WebView so clients can set the isInspectable flag and debug on XCode 14.3+.

Any other use of the private Webview object, such as loading another web page, may lead to unpredictable behavior and is strongly discouraged.

 tealium?.getTagManagementWebView { webView in
    if #available(iOS 16.4, *) {
        webView.isInspectable = true // To inspect tagManagement webviews on XCode 14.3+ and iOS 16.4+
    }
  }

joinTrace()

Joins a trace with the specified ID. The trace remains active for the duration of the app session until leaveTrace() is called. Learn more about the trace feature in the Tealium Customer Data Hub.

joinTrace(traceId: String)

leaveTrace()

Leave a previously joined trace and end the visitor session. Optional parameter to preserve the trace visitor session when leaving the trace.

tealium?.leaveTrace(killVisitorSession: false)

linkECIDToKnownIdentifier()

Links the current ECID to a known secondary identifier, such as an email address or other internal ID.

linkECIDToKnownIdentifier(
  _ knownID: String,
  adobeDataProviderId: String,
  authState: AdobeVisitorAuthState?,
  completion: ((Result<AdobeVisitor, Error>) → Void)

Example:

var tealium: Tealium?
...

tealium?.adobeVisitorApi?.linkECIDToKnownIdentifier(
  "myidentifier", adobeDataProviderId: "123456", .unknown
  )

onVisitorId

Notifies of visitor ID changes.

let subscription = tealium?.onVisitorId.subscribe { newVisitor in
    // handle visitor change here
}

resetVisitor()

Resets the visitor ECID by retrieving a new one on the next tracking call.

resetVisitor()

Example:

var tealium: Tealium?
//...
tealium?.adobeVisitorApi?.resetVisitor()

resetVisitorId()

Generates a new visitor ID for the user.

tealium?.resetVisitorId()

startTimedEvent()

Starts a timed event with the given name. If this method is called again with the same event name, it is ignored if the event has not been ended or canceled. The event start time is not persisted.

If optional data is passed along with the event name, it is added to the track call when the timer is stopped with the stopTimedEvent() call.

tealium.startTimedEvent(name: "TIMED_EVENT_NAME", with: ["custom_key": "custom_value"])

stopTimedEvent()

Stops the timer for a timed event which triggers the timed_event tracking call.

tealium?.stopTimedEvent(name: "TIMED_EVENT_NAME")

Tealium()

Constructor for a new Tealium object.

Tealium(config: TealiumConfig, completion: Closure)

track()

Tracks a screen view or event with optional event data.

tealium?.track(tealiumEvent)

To track events, pass a TealiumView or TealiumEvent object to the track() method:

let tealiumEvent = TealiumView(
  "purchase",
  dataLayer: [
    "customer_id": "abc123", 
    "order_total": 10.00,
    "product_id": ["PROD123", "PROD456"], 
    "order_id": "0123456789"
  ]
)
tealium?.track(tealiumEvent)

visitor

Returns the full AdobeVisitor instance.

var tealium: Tealium?
//...
let visitor = tealium?.adobeVisitorApi?.visitor
let id: String? = visitor?.experienceCloudId
let nextRefresh: Date? = visitor?.nextRefresh
let blob: String? = visitor?.blob
let region: String? = visitor?.dcsRegion
let ttl: String? = visitor?.idSyncTTL

visitorId

Returns a randomly generated and unique persistent visitor ID.

let visitorId: String? = tealium.visitorId

Interface: TealiumDispatch

An interface that defines the type of dispatch to be tracked. The following classes implement TealiumDispatch:

Class: TealiumEvent

To track a user’s interaction with a screen or a screen view, pass an instance of TealiumEvent(tealiumEvent:dataLayer:) to the Track() method. TealiumEvent consists of an event name, which appears in the tracking call as tealium_event, and an optional data dictionary.

let tealEvent = TealiumEvent(tealiumEvent, dataLayer: eventData)
tealium?.track(tealEvent)

Example:

let tealEvent = TealiumEvent(
  "cart_add", 
  dataLayer: [
    "customer_id": "abc123", 
    "product_id": ["PROD123", "PROD456"], 
    "product_price": [4.00, 6.00]
  ]
)
tealium?.track(tealEvent)

Class: TealiumView

To track screen views, pass an instance of TealiumView(tealiumEvent:dataLayer:) to the Track() method. TealiumView consists of a view name, which appears in the tracking call as tealium_event, and an optional data dictionary.

let screenView = TealiumView(tealiumEvent, dataLayer: eventData)
tealium?.track(screenView)

Example:

let screenView = TealiumView(
  "purchase", 
  dataLayer: [
    "customer_id", "abc123", 
    "order_total": 10.00, 
    "product_id": ["PROD123", "PROD456"],     
    "order_id": "0123456789"
  ]
)
tealium?.track(screenView)