Quick start guide for Tealium Prism

Install

To install the Tealium Prism Kotlin library with Maven:

In your Android project, add the following maven repository:

dependencyResolutionManagement {
    repositories {
        // .. other repos
        maven {
            url = URI("https://maven.tealiumiq.com/android/releases/")
        }
    }
}

In your project module’s build.gradle file, add the following dependencies. You only need to specify the version number for the platform() entry:

implementation(platform("com.tealium.prism:prism-bom:0.4.0"))
implementation("com.tealium.prism:prism-core")
implementation("com.tealium.prism:prism-lifecycle")
implementation("com.tealium.prism:prism-moments-api")

To install Tealium Prism Swift with Swift Package Manager:

In your Xcode project, select File > Swift Packages > Add Package Dependency
Enter the repository URL: https://github.com/tealium/tealium-prism-swift
Configure the version rules. Typically, Up to next major is recommended. If the current Tealium Prism Swift library version does not appear in the list, then reset your Swift package cache.
Select the modules to install and add the modules to each of your app targets in your Xcode project, under Frameworks > Libraries & Embedded Content.

To install with Cocoapods, add the following line to your podfile:

pod 'tealium-prism'

Initialize

To initialize Tealium, pass a TealiumConfig instance to the Tealium.create() method. We recommended initializing the Tealium Kotlin library in the app’s global application class within the onCreate() method.

import com.tealium.prism.core.api.Tealium
import com.tealium.prism.core.api.TealiumConfig

val config = TealiumConfig.Builder(
   accountName = "my_account",
   profileName = "my_profile",
   environment = Environment.PROD,
   modules = listOf(
        Modules.appData(),
        Modules.collect(),
        Modules.connectivityData(),
        Modules.deepLink(),
        Modules.deviceData(),
        Modules.lifecycle(),
        Modules.timeData(),
        Modules.trace(),
       )
).build()
val tealium = Tealium.create(config)
tealium.track("test_event")

To initialize Tealium, pass a TealiumConfig instance to the Tealium.create() static method.

#if COCOAPODS
import TealiumPrism
#else
import TealiumPrismCore
#endif

let config = TealiumConfig(account: "my_account",
                           profile: "my_profile",
                           environment: "prod",
                           settingsUrl: "https://tags.tiqcdn.com/dle/my_account/my_profile/prod/settings.json")
let tealium = Tealium.create(config: config)

If you don’t want to use remote settings, or want a local copy of those settings to provide different defaults, specify a local settings file:

#if COCOAPODS
import TealiumPrism
#else
import TealiumPrismCore
#endif

let config = TealiumConfig(account: "my_account",
                           profile: "my_profile",
                           environment: "prod",
                           settingsFile: "my_settings",
                           settingsUrl: "https://tags.tiqcdn.com/dle/my_account/my_profile/prod/settings.json")
let tealium = Tealium.create(config: config)

To configure the entire SDK programmatically, enable specific modules by default, or modify module settings, add the modules to the configuration:

#if COCOAPODS
import TealiumPrism
#else
import TealiumPrismCore
import TealiumPrismLifecycle
import TealiumPrismMomentsAPI
#endif

let config = TealiumConfig(account: "my_account",
                           profile: "my_profile",
                           environment: "prod",
                           modules: [
                            Modules.appData(),
                            Modules.collect(),
                            Modules.connectivityData(),
                            Modules.deepLink(),
                            Modules.deviceData(),
                            Modules.lifecycle(),
                            Modules.momentsAPI(),
                            Modules.timeData(),
                            Modules.trace(),
                           ],
                           settingsFile: "my_settings",
                           settingsUrl: "https://tags.tiqcdn.com/dle/my_account/my_profile/settings.json",
)
let tealium = Tealium.create(config: config)

Each module can specify additional programmatic configuration. This overrides local and remote configuration and cannot be changed remotely. The following example specifies settings for the Collect module, which are enforced at compile time and cannot be updated by remote settings. Other settings not programmatically configured can be updated remotely.

Modules.collect { enforcedSettings in
    enforcedSettings.setEnabled(true)
        .setOrder(5)
        .setOverrideProfile("custom_profile")
        .setOverrideDomain("custom_domain")
}

Track

To track events, pass name, type, and data to the track() method. The name of the event appears in the data layer as tealium_event.

To track events, call track().

tealium.track("user_login", DataObject.create {
    put("customer_id", "1234567890")
})

To track events, call track().

/// Basic Track with default event type and empty data layer.
tealium.track("homepage")

/// Track with full paraemters
tealium.track("user_login", type: .event, dataLayer: ["customer_id": "1234567890"])

/// Track with different view type
tealium.track("homepage", type: .view)

Data Layer

To add data to the data layer:

To get a data layer value use the get() method and subscribe if you need to handle the result or an error:

tealium.dataLayer.getString("customer_id").subscribe { result ->
    val customerId = result.getOrNull()
    // do something with customerId
}

To set a data layer value use the put() method:

tealium.dataLayer.put("my_string", "my_string_value")

To set a data layer object use the DataObject.Builder():

val globalContext = DataObject.Builder()
    .put("customer_id", "12345")
    .put("is_logged_in", true)
    .put("consent_status", "consented")
    .build()

dataLayer.put(globalContext, Expiry.FOREVER)

Use individual put operations only when atomicity is not required, because each call runs independently and in sequence. When setting multiple values and timing or consistency is important, use transactionally to apply all updates in a single atomic operation so they either all succeed or all fail.

tealium.dataLayer.transactionally { editor ->
    editor.put("key", "value".asDataItem(), Expiry.SESSION)
        .put("key2", "value2".asDataItem(), Expiry.SESSION)
        .remove("key2")
        .commit()
}.onFailure {
    Log.d("DataLayer", "Transactional update failed: ${it.message}")
}

To set an array value use the DataList.Builder():

val productCategories = DataList.create {
  add("electronics")
  add("headphones")
}

dataLayer.put(
    key = "product_category",
    value = productCategories,
    expiry = Expiry.SESSION
).subscribe({ }, { err -> })

To set an expiration of the data use Expiry:

dataLayer.put(
    key = "currency",
    value = DataItem(any = "USD"),
    expiry = Expiry.UNTIL_RESTART
)
dataLayer.put(
    key = "order_total",
    value = 249.95,
    expiry = Expiry.afterTimeUnit(7, TimeUnit.DAYS)
)

To get a data layer value, call the get() method:

tealium.dataLayer.get(key: "customer_id",
                      as: String.self).subscribe { result in
    switch result {
    case .success(let value):
        print("Optional Value: \(String(describing: value))")
    case .failure(let error):
        print("Error: \(error)")
    }
}

To set a data layer value, use the put() method.

tealium.dataLayer.put(key: "some_key", value: "some value")

To set a data layer object use the DataObject():

tealium.dataLayer.put(data: [
    "customer_id": "12345",
    "is_logged_in": true,
    "consent_status": "consented",
    "product_category": ["electronics", "headphones"]
])

To set an expiration of the data use Expiry:

tealium.dataLayer.put(key: "currency", 
                      value: "USD", 
                      expiry: .untilRestart)

tealium.dataLayer.put(key: "order_total", 
                      value: 249.95, 
                      expiry: .after(Date().advanced(by: 1000)))

Validate

Validate your data by inspecting log files, running a trace, and viewing live events.

Logs

To set the log level, call setLogLevel() in the settings of the TealiumConfig builder:

val config = TealiumConfig.Builder(...)
  .configureSettings { settings ->
    settings.setLogLevel(LogLevel.WARN)
  }

For more information, see LogLevel.

To set the log level, call setMinLogLevel() in the settings of the TealiumConfig builder:

var config = TealiumConfig(account: "your_account",
                           profile: "you_profile",
                           environment: "dev",
                           modules: [],
                           settingsFile: nil,
                           settingsUrl: nil,
                           forcingSettings: { builder in
    builder.setMinLogLevel(.trace) // or .debug, .info, .warn, .error, .silent
})

Trace

The Mobile Trace Tool enhances the trace feature by providing a QR code scannable by your device, enabling you to quickly view events coming from a Tealium mobile SDK.

Learn more about using the Trace Interface.

trace.join("TRACE_ID")

// Leave the current trace session
trace.leave()

// Force end of visit for testing
trace.forceEndOfVisit()

Lear more about using the Trace Protocol Reference.

// Join a trace session
tealium.trace.join(id: "TRACE_ID")

// Leave the current trace session
tealium.trace.leave()

// Force end of visit for testing
tealium.trace.forceEndOfVisit()

Live events

Use live events to troubleshoot mobile installations.

Learn more about Live events.