Quick Start Guide

Install

Get started with installing Tealium for Android or iOS.

To install Tealium for Android library with Maven:

Add the Tealium Maven URL to your project’s top-level build.gradle file:

allprojects {
  repositories {
    jcenter()
    maven {
      url "https://maven.tealiumiq.com/android/releases/"
    }
  }
}

In your project module’s build.gradle file, add the following Maven dependency:
```
dependencies {
  implementation 'com.tealium:kotlin-core:1.X.X'
}
```

Check for the latest releases on Github and replace 1.X.X with the latest release number.

To install Tealium for iOS library with Swift Package Manager:

In your Xcode project, select File > Swift Packages > Add Package Dependency
Enter the repository URL: https://github.com/tealium/tealium-swift
Configure the version rules. Typically, Up to next major is recommended. If the current Tealium 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

Initialize

Get started with initializing Tealium for Android or iOS.

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.

Manage your Tealium instance by using a tracking helper class, which provides a single point of entry for the Tealium Kotlin library and simplifies future upgrades.

object TealiumHelper {

  lateinit var tealium: Tealium

  fun init(application: Application) {
    val tealiumConfig = TealiumConfig(
                      application,
                      "ACCOUNT",
                      "PROFILE",
                      Environment.DEV,
                      dataSourceId = "DATASOURCE_ID",  //optional
                      modules = mutableSetOf(VisitorService),
                      dispatchers = mutableSetOf(TagManagement, Collect)
                    )
    tealium = Tealium.create("tealium_instance", tealiumConfig)
  }
}

To initialize Tealium, pass a TealiumConfig instance to the Tealium() constructor.

Manage your Tealium instance by using a tracking helper class, which provides a single point of entry for the Tealium iOS library and simplifies future upgrades.

class TealiumHelper {
    static let shared = TealiumHelper()
    let config = TealiumConfig(account: "ACCOUNT",
                               profile: "PROFILE",
                               environment: "ENVIRONMENT",
                               datasource: "DATASOURCE")
    var tealium: Tealium?

    private init() {

        // add necessary config options
        config.batchingEnabled = true
        config.logLevel = .debug

        // add desired Collectors - no need to include if want all compiled collectors
        config.collectors = [Collectors.Lifecycle,
                             Collectors.Location,
                             Collectors.VisitorService]

        // add desired Dispatchers - no need to include if want compiled dispatchers
        config.dispatchers = [Dispatchers.TagManagement,
                              Dispatchers.RemoteCommands]

        tealium = Tealium(config: config)

        // optional post init processing
        tealium?.dataLayer.add("mykey", "myvalue", expiry: .forever)

    }

    public func start() {
        _ = TealiumHelper.shared
    }

    class func trackView(title: String, data: [String: Any]?) {    
      let tealView = TealiumView(title, dataLayer: data)
      TealiumHelper.shared.tealium?.track(tealView)
    }

    class func trackEvent(title: String, data: [String: Any]?) {
      let tealEvent = TealiumEvent(title, dataLayer: data)
      TealiumHelper.shared.tealium?.track(tealEvent)
    }
}

Mobile Publish Settings are enabled by default, and must be disabled if you don’t wish to use them. Configure the Mobile Publish Settings in iQ Tag Management, or disable them using config.shouldUseRemotePublishSettings = false.

Track

Get started with tracking views and events for Android or iOS.

Track Views

To track screen views, pass an instance of TealiumView(viewName:dataLayer:) to the track() method. TealiumView is comprised of a view name, which appears in the data layer as tealium_event, and an optional data dictionary.

To track views:

val tealView = TealiumView("screen_view", mutableMapOf("screen_name" to "Home"))
tealium.track(tealView);

To track views:

let tealView = TealiumView("screen_view", dataLayer: ["screen_name": "Home"])
tealium?.track(tealView)

Track Events

To track non-view events, pass an instance of TealiumEvent(eventName:dataLayer:) to the track() method. TealiumEvent is comprised of an event name, which appears in the data layer as tealium_event, and an optional data dictionary.

To track events:

val tealEvent = TealiumEvent("user_login", mutableMapOf("customer_id" to "1234567890"))
tealium.track(tealEvent);

To track events:

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

The track() method tracks an event by accepting a TealiumDispatch of type TealiumEvent, which is comprised of an event name and an optional data dictionary.

Data Layer

Get started managing common data layer values and the data provided by each module for Android or iOS.

To add data to the data layer:

To set a String value use the putString() method:

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

Similarly for different data types, the method begins with put, such as putInt() for integers and putDoubleArray() for an array of floating-point numbers. Learn more about methods for different data type.

To set a String value to expire after 1 day:

tealium.dataLayer.putString("my_string", "my_string_value", Expiry.afterTimeUnit(1, TimeUnit.DAYS))

Learn more about the expiration types.

To set a value of any type, use the add() method:

tealium.dataLayer.add(key: "my_value", value: 123456)

To set a value of any type to expire after 1 day:

tealium?.dataLayer.add(key: "my_value", value: 123456, expiry: .afterCustom((.days, 1)))

Identify

Get started with adding a custom visitor ID for Android or iOS.

Visitor ID

The Tealium Android and Swift libraries generates a unique persistent visitor ID the first time it is launched and stores it in visitorId. This value is the primary visitor ID included in each tracked event as the attribute tealium_visitor_id.

To get the visitor ID:

class TealiumHelper {
    lateinit var tealium: Tealium

    fun getVisitorId(): String {
        return tealium.visitorId
    }
}

To get the visitor ID:

class TealiumHelper {
    var tealium: Tealium?

    var visitorId: String? {
        tealium?.visitorId
    }
}

Provide additional visitor ID attributes to the data layer, as needed, by sending them as variables in your tracking calls.

If you are using Tealium AudienceStream, visitorId is the primary visitor ID associated with the visitor. Learn more about configuring visitor IDs in AudienceStream.

Secondary Visitor ID

Include secondary visitor ID attributes as needed by adding them to the persistent data storage.

To add a known visitor ID, such as a customer ID:

fun setKnownVisitorId(id: String) {
    tealium.dataLayer.putString("customer_id", id, Expiry.FOREVER)
}

To add a known visitor ID, such as a customer ID:

func setKnownVisitorId(_ id: String) {
    tealium?.dataLayer.add(key: "customer_id", value: id, expiry: .forever)
}

Validate

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

Logs

Get started with logging for Android or iOS.

To set the log level, set the logLevel property:

Logger.logLevel = LogLevel.DEV // or LogLevel.QA, LogLevel.PROD

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.

To join a trace, call the joinTrace() method:

Tealium["INSTANCE_NAME"]?.joinTrace("TRACE_ID")

To leave a trace, call the leaveTrace() method:

Tealium["INSTANCE_NAME"]?.leaveTrace()

To join a trace, call the joinTrace() method:

tealium?.joinTrace(id: "TRACE_ID")

To leave a trace, call the leaveTrace() method:

tealium?.leaveTrace()

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

Live Events

The Live Events feature in Tealium EventStream is available to all Tealium customers for the purpose of toubleshooting mobile installations.

Learn more about using Live Events.

Mobile Concepts