Quick start

This guide walks you through creating a mobile profile, installing the Prism SDK, initializing a Tealium instance, sending your first tracking call, and validating the results.

Create a mobile profile

Before you install the SDK, create a mobile profile in Tag Management. For instructions, see Create a mobile profile.

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.7.0"))
implementation("com.tealium.prism:prism-core")
implementation("com.tealium.prism:prism-lifecycle")
implementation("com.tealium.prism:prism-context-api")

The following Prism Kotlin modules are available as individual dependencies:

prism-core (required)
prism-lifecycle
prism-context-api

The AppData, Collect, ConnectivityData, DeepLink, DeviceData, TimeData, and Trace modules are included in prism-core.

To install Tealium Prism Swift with Swift Package Manager:

In your Xcode project, select File > Add Package Dependencies.
Enter the repository URL: https://github.com/tealium/tealium-prism-swift.
Configure the version rules. We recommend configuring Up to next major. If the current Tealium Prism Swift library version does not appear in the list, 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'

The following Prism Swift modules are available as individual dependencies:

TealiumPrismCore (required)
TealiumPrismLifecycle
TealiumPrismContextAPI

The AppData, Collect, ConnectivityData, DeepLink, DeviceData, DataLayer, TimeData, and Trace modules are included in TealiumPrismCore.

Tealium Prism React Native requires React Native 0.85 with the New Architecture (TurboModules).

To install the Tealium Prism React Native library with npm:

npm install @tealium/prism-react-native @tealium/prism-react-native-lifecycle

To install with Yarn instead:

yarn add @tealium/prism-react-native @tealium/prism-react-native-lifecycle

To install the native iOS dependencies:

cd ios && pod install

Android requires no additional steps.

For detailed installation instructions including CocoaPods, see Install.

Initialize

To initialize Tealium, pass a TealiumConfig instance to the Tealium.create() method. We recommend 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
import com.tealium.prism.core.api.Modules
import com.tealium.prism.core.api.misc.Environment
import com.tealium.prism.lifecycle.lifecycle

val config = TealiumConfig.Builder(
   application = application,
   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)

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/mobile_settings_prod.json")
let tealium = Tealium.create(config: config)

To configure the SDK programmatically and enable specific modules, add the modules to the configuration:

#if COCOAPODS
import TealiumPrism
#else
import TealiumPrismCore
import TealiumPrismLifecycle
import TealiumPrismContextAPI
#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.contextAPI(),
                            Modules.timeData(),
                            Modules.trace(),
                           ],
                           settingsFile: "my_settings",
                           settingsUrl: "https://tags.tiqcdn.com/dle/my_account/my_profile/mobile_settings_prod.json")
let tealium = Tealium.create(config: config)

To initialize Tealium, call Tealium.create() with your account, profile, and environment. We recommend creating one instance when the app starts and sharing it across your app.

import { Tealium, Environment } from "@tealium/prism-react-native";

const tealium = Tealium.create(
  "my_account",
  "my_profile",
  Environment.prod,
  "my_settings.json",
  "https://tags.tiqcdn.com/dle/my_account/my_profile/mobile_settings_prod.json"
);

On iOS, add the settings file to your app target. On Android, put the settings file in android/app/src/main/assets/.

The installed packages and your Tealium settings decide which modules run.

For more details on configuration options, see Install.

Track

To track events, pass an event name and optional 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 parameters
tealium.track("user_login", type: .event, data: ["customer_id": "1234567890"])

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

To track events, call track(). track() returns a Promise that rejects if the SDK cannot serialize the data.

// Track an event with the default type.
await tealium.track("homepage");

// Track an event with data.
await tealium.track("user_login", "event", { customer_id: "1234567890" });

// Track a view.
await tealium.track("homepage", "view");

For more details on tracking, see Track.

Data layer

To add data to the data layer:

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

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

To get a data layer value, use the get() method and subscribe to handle the result:

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

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.putAll(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
).onFailure { err -> }

To set an expiration of the data use Expiry:

dataLayer.put(
    key = "currency",
    value = "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 multiple data layer values at once, pass a dictionary to putAll(dataObject:):

tealium.dataLayer.putAll(dataObject: [
    "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)))

To get a data layer value, call get() on tealium.dataLayer:

const customerId = await tealium.dataLayer.get("customer_id");

To set a data layer value, call put():

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

To set several values in one call, pass a plain object to putAll():

await tealium.dataLayer.putAll({
  customer_id: "12345",
  is_logged_in: true,
  consent_status: "consented",
  product_category: ["electronics", "headphones"],
});

To set an expiration of the data, pass an expiry as the last argument:

await tealium.dataLayer.put("currency", "USD", "untilRestart"); // or "session", "forever"

const sevenDays = 7 * 24 * 60 * 60 * 1000;
await tealium.dataLayer.put("order_total", 249.95, new Date(Date.now() + sevenDays));

To get every data layer value, call getAll():

const data = await tealium.dataLayer.getAll();

To remove data layer values, call remove() with a key or an array of keys:

await tealium.dataLayer.remove("customer_id");
await tealium.dataLayer.remove(["is_logged_in", "consent_status"]);

To remove every data layer value, call clear():

await tealium.dataLayer.clear();

For more details on the data layer, see Data layer.

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(...)
  .configureCoreSettings { 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: "your_profile",
                           environment: "dev",
                           modules: [],
                           settingsFile: nil,
                           settingsUrl: nil,
                           forcingSettings: { builder in
    builder.setMinLogLevel(.trace)
})

To set the log level, pass a LogLevel as the sixth argument of Tealium.create(). Pass undefined for the settings arguments that you do not use:

const tealium = Tealium.create(
  "my_account",
  "my_profile",
  Environment.dev,
  undefined,
  undefined,
  "debug" // or "trace", "info", "warn", "error", "silent"
);

Trace

The Mobile Trace Tool provides a QR code you can scan with your device to view live events 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()

Learn 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()

Learn more about using the Trace interface.

// Join a trace session.
await tealium.trace.join("TRACE_ID");

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

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

To use these calls, enable the Trace module in your Tealium settings. Otherwise, the Promise rejects.

Live events

Use live events to troubleshoot mobile installations.

Learn more about Live events.