API Reference

Class: Tealium

The following summarizes the commonly used methods of the Cordova Tealium class.

addRemoteCommand()

Adds a remote command to the remote command manager.

tealium.addRemoteCommand(id, callback);

Example:

tealium.addRemoteCommand("firebase", (payload) => {

  var eventName = payload["firebase_event_name"];
  var eventProperties = payload["firebase_event_properties"];

  analytics.logEvent(eventName, eventProperties);
});

addData()

Adds data to the persistent data storage for the given expiration.

tealium.addData(data, expiry);

Collectors

Collectors are modules that gather supplemental information from the device and append it to the data layer before it’s transmitted to the Tealium Customer Data Hub. Some collectors are included in the core library, while others are optional and installed as separate modules.

The following table lists the available collectors. Default collectors are denoted by a * next to the collector name.

These modules are enabled or disabled using the collectors property of your config object, and the constant values are available from window.tealium.utils.Collectors.

ConsentExpiry

Defines the consent preferences expiration

Example:

var ConsentExpiry = tealium.utils.ConsentExpiry
var TimeUnit = tealium.utils.TimeUnit
ConsentExpiry.create(90, TimeUnit.days)

TimeUnit

ConsentPolicy

Defines the consent policy to adhere to. If no consent policy is defined on the config object, the consent manager becomes disabled. Constants are available from window.tealium.utils.ConsentPolicy.

Example:

var ConsentPolicy = tealium.utils.ConsentPolicy
var gdpr = ConsentPolicy.gdpr

Dispatchers

Dispatchers are modules that send the data from your data layer and send it to a Tealium endpoint. The following dispatchers are currently available - Constants are available from window.tealium.utils.Dispatchers.

At least one dispatcher is required. If no dispatchers are specified, your data is not sent anywhere.

Expiry

Defines the custom data expiration.

Example:

Expiry.session

Example:

var Expiry = tealium.utils.Expiry
var session = Expiry.session

gatherTrackData()

Gathers all track data from collectors and data layer.

tealium.gatherTrackData(callback)

Example:

  tealium.gatherTrackData(function(data) {
    console.log(data)
  });

getData()

Retrieves the value for a specified key in the persistent data layer, then returns in the form of a callback function.

tealium.getData(key, callback);

Example:

tealium.getData(key, function(data) {
  console.log(data)
});

getConsentCategories()

Retrieves the user’s consented categories.

tealium.getConsentCategories(callback);

Example:

tealium.getConsentCategories(categories => {
    console.log("Consent Categories: " + categories)
});

getConsentStatus()

Retrieves the user’s visitor ID and returns in the form of a callback function.

tealium.getConsentStatus(callback);

Example:

tealium.getConsentStatus(function(categories) {
  console.log("Consent Status: " + status)
})

getVisitorId()

Retrieves the user’s visitor ID and returns in the form of a callback function.

tealium.getVisitorId(callback);

Example:

tealium.getVisitorId(function(visitorId) {
  console.log("VisitorId: " + visitorId)
})

initialize()

Initialize Tealium before calling any other method.

tealium.initialize(config);

Example:

let Environment = tealium.utils.Environment;
let Collectors = tealium.utils.Collectors;
let Dispatchers = tealium.utils.Dispatchers;
let ConsentPolicy = tealium.utils.ConsentPolicy;
let Expiry = tealium.utils.Expiry;

let config = {
    account: 'tealiummobile',
    profile: 'demo',
    environment: Environment.dev,
    dispatchers: [
        Dispatchers.Collect,
        Dispatchers.TagManagement,
        Dispatchers.RemoteCommands
    ],
    collectors: [
        Collectors.AppData,
        Collectors.DeviceData,
        Collectors.Lifecycle,
        Collectors.Connectivity
    ],
    consentLoggingEnabled: true,
    // consentExpiry: {
    //     'time': 10,
    //     'unit': 'days'
    // },
    // consentPolicy: ConsentPolicy.gdpr,
    lifecycleAutotrackingEnabled: true,
    batchingEnabled: false,
    visitorServiceEnabled: true,
    useRemoteLibrarySettings: false
};

window.tealium.initialize(config, function(success) {
    console.log("Init was: " + success)
    if(success) {
        tealium.setVisitorServiceListener(logVisitorUpdated)
        tealium.setConsentExpiryListener(logConsentExpired)
        tealium.addRemoteCommand("hello-world", logRemoteCommand)
    }
})

joinTrace()

Joins a trace with the specified ID. Learn more about the Trace feature in the Tealium Customer Data Hub.

tealium.joinTrace(id);

leaveTrace()

A trace remains active for the duration of the app session until the leaveTrace() method is called, which leaves a previously joined trace and ends the visitor session.

tealium.leaveTrace();

LogLevel

Sets the log level property, which controls how much information is logged, to one of the following values:

Example:

LogLevel.dev

setConsentCategories()

Sets the consent categories of a user. Pass in an array of Strings to set the categories. Default is an empty array until ConsentStatus is set to .consented. If the consent status is .consented and no categories are specified with the setConsentCategories() method, then all categories are set.

tealium.setConsentCategories(categories);

Example:

var ConsentCategories = tealium.utils.ConsentCategories;

tealium.setConsentCategories([ConsentCategories.analytics, ConsentCategories.email]);

ConsentCategories

setConsentExpiryListener()

Defines a callback to execute after the user’s consent preferences have expired according the ConsentExpiry.

tealium.setConsentExpiryListener(callback);

Example:

tealium.setConsentExpiryListener(() => {
    print("Consent Expired");
});

setConsentStatus()

Sets the consent status of a user. Default is .unknown until changed.

tealium.setConsentStatus(status);

Example:

var ConsentStatus = window.tealium.utils.ConsentStatus

tealium.setConsentStatus(ConsentStatus.consented);

ConsentStatus

setVisitorServiceListener()

Defines a callback to execute when the visitor profile has been updated. The updated VisitorProfile is provided in the callback response.

The VisitorService module implements the Data Layer Enrichment feature of the Tealium Customer Data Hub.

Usage of this module is recommended if you are licensed for Tealium AudienceStream and you want to use the visitor profile to enhance the user experience in your mobile application. If you are not licensed for AudienceStream, usage of this module is not recommended as no visitor profile is returned.

tealium.setVisitorServiceListener(callback);

Example:

tealium.setVisitorServiceListener((profile) => {
    console.log(JSON.stringify(profile));
});

removeData()

Remove persistent data that has been previously set using tealium.addData().

tealium.removeData(keys);

removeRemoteCommand()

Removes a remote command from the remote command manager.

tealium.removeRemoteCommand(id);

Example:

tealium.removeRemoteCommand("firebase");

TealiumEnvironment

The environment is one of three default environments (Dev, QA, Prod) or any custom environments that Tealium publishes to. Select one of these environments. Constants are available from window.tealium.utils.Environment.

Example:

Environment.dev

Config

The following summarizes the properties of the config options and their keys.

Dispatch

An interface that defines the type of dispatch to be tracked.

View

To track a screen view, pass an object wit viewName and optional dataLayer to the track() method. These may be supplied manually or via the utility methods at tealium.utils.Dispatch.view(viewName, dataLayer).

var Dispatch = tealium.utils.Dispatch;
var screenView = Dispatch.view(tealiumEvent, eventData);
tealium.track(screenView);

var Dispatch = tealium.utils.Dispatch;

var screenView = Dispatch.view(
  'purchase', 
  {
    "customer_id": "abc123", 
    "order_total": 10.00, 
    "product_id": ["PROD123", "PROD456"], 
    "order_id": "0123456789"
  }
);
tealium.track(screenView);

// the following is equivalent
tealium.track({
  type: "view",
  viewName: "purchase",
  dataLayer: {
    "customer_id": "abc123", 
    "order_total": 10.00, 
    "product_id": ["PROD123", "PROD456"], 
    "order_id": "0123345789"
  }
})

Event

To track non-view events, pass an object with eventName and optional eventData to the track() method. These may be supplied manually or via the utility methods at tealium.utils.Dispatch.event(eventName, dataLayer).

var Dispatch = tealium.utils.Dispatch;
var tealiumEvent= Dispatch.view(tealiumEvent, eventData);
tealium.track(tealiumEvent);

var Dispatch = tealium.utils.Dispatch
var tealEvent = Dispatch.event(
  "cart_add", 
  {
    "customer_id": "abc123", 
    "product_id": ["PROD123", "PROD456"], 
    "product_price": [4.00, 6.00]
  }
)
tealium.track(tealEvent)

// the following is equivalent
tealium.track({
  type: "event",
  eventName: "cart_add",
  dataLayer: {
    "customer_id": "abc123", 
    "product_id": ["PROD123", "PROD456"], 
    "product_price": [4.00, 6.00]
  }
})

terminateIntance()

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

tealium.terminateIntance();

track()

Tracks a screen view or event with optional associated data.

tealium.track(tealiumEvent)

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

var Dispatch = tealium.utils.Dispatch
var tealEvent = Dispatch.event(
  "cart_add", 
  {
    "customer_id": "abc123", 
    "product_id": ["PROD123", "PROD456"], 
    "product_price": [4.00, 6.00]
  }
)
tealium.track(tealEvent)

// the following is equivalent
tealium.track({
  type: "event",
  eventName: "cart_add",
  dataLayer: {
    "customer_id": "abc123", 
    "product_id": ["PROD123", "PROD456"], 
    "product_price": [4.00, 6.00]
  }
})

VisitorProfile

The visitor profile is an object that contains friendly names for each attribute. There is a currentVisit property that lets you distinguish visitor/visit attribute types. Access each attribute value by ID using a subscript. If the attribute does not exist, null is returned. See the below list for examples.

Attribute Types

RemoteCommand

An interface that defines a configured Remote Command

The path and URL are optional, but either provide only one or the other, or omit both in the case where the mappings are handled by a tag in Tealium iQ Tag Management.

Provide the callback if the command is to be handled within the scope of your React Native app. Omit the callback if the handler has already been registered natively.

The following example is a local mappings file for a command handled by Javascript:

let localCommand: RemoteCommand = {
    id: "hello-world",
    path: "hello-mappings.json",
    callback: (payload) => {
        //...
    }
}

The following example is a remote mappings file for a command handled natively:

let remoteNativeCommand: RemoteCommand = {
    id: "hello-world",
    url: "https://you.domain.com/hello-mappings.json"
}