Quick start guide

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, configure a []TealiumConfig]() instance and pass it into a Tealium instance. It’s recommended to initialize 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() constructor.

#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: nil,
                           settingsUrl: nil)
let tealium = Tealium.create(config: config)
tealium.track("test_event")

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.

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

let tealEvent = TealiumEvent("user_login", dataLayer: ["customer_id": "1234567890"])
tealium?.track(tealEvent)

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)

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 set a value of any type to never expire:

tealium.dataLayer.put(key: "some_key", value: "some value", expiry: .forever).subscribe { result in
            // Optionally handle result here
        }

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, set the logLevel property:

config.logLevel = .debug // or .info, .error, .fault, .silent

Trace

Get started with trace for Android or iOS.

trace.join("TRACE_ID")

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

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

Use trace by accessing an interface on the Tealium object:

// Join a trace session
tealium.trace.join(id: "TRACE_ID").subscribe { result in
    // Optionally handle result here
}

// Leave the current trace session
tealium.trace.leave().subscribe { result in
    // Optionally handle result here
}

// Force end of visit for testing
tealium.trace.forceEndOfVisit().subscribe { result in
    // Handle the track result
}

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.

Live events

Use the live events feature to troubleshoot mobile installations.

Learn more about Live events.