Install

Requirements

Cordova 7.0.0
CocoaPods

The plugin includes the following Tealium libraries:

As of version 1.1.1, framework files are no longer included in the plugin. Instead, the respective dependency managers are used for iOS and Android.

NPM (Recommended)

The NPM package name is:

tealium-cordova-plugin

To install the plugin via NPM, issue this command on the terminal from within your project directory:

cordova plugin add tealium-cordova-plugin

Manual

If you cannot use NPM, you may install the plugins manually. From the Command Line Interface (CLI), first:

cd your_project_folder/
cordova platform add <PLATFORM>
cordova plugin add </LOCAL_PATH_TO_TEALIUM_PLUGIN/>
cordova build <PLATFORM>

Initialize

Once the Tealium Cordova plugin is installed you are ready to start coding. The initialization function takes the following parameters:

account - the name of your account
profile - the name of the profile within your account
environment - (optional) one of “qa” or “prod”
instance - the instance name (multiple instances can be created, each with a unique name)
datasource - (optional) the data source key from UDH
isLifecycleEnabled - (optional) string value “true” or “false” to control lifecycle tracking (default: “true”)
isCrashReporterEnabled - (optional, Android only, requires Crash Reporter plugin) string value “true” or “false” to control crash report tracking
logLevel - (optional) set a different log level than the environment (defaults to the environment)
- tealium.logLevels.DEV
- tealium.logLevels.QA
- tealium.logLevels.PROD

tealium.init({
    account                  : "your_account"
    , profile                : "your_profile"
    , environment            : "dev"
    , instance               : "tealium"
    , isLifecycleEnabled     : "false"
    , isCrashReporterEnabled : "true"
    , logLevel               : tealium.logLevels.DEV
    , collectDispatchProfile : "us-mobile"
    , collectDispatchURL     : "us-mobile"
});

Endpoint Override

By default, the core iOS and Android libraries send Tealium Collect data to the “main” profile of your account. Use one of these initialization options to override this behavior:

collectDispatchProfile - specify an alternate profile to use in the Tealium Collect endpoint

Example:

tealium.init({
    account                : "your_account",
    profile                : "us-mobile",
    environment            : "prod",
    instance               : window.tealium_instance,
    collectDispatchProfile : "us-mobile"
});

collectDispatchURL - specify a full alternate Tealium Collect endpoint

Example:

tealium.init({
    account            : "your_account",
    profile            : "us-mobile",
    environment        : "prod",
    instance           : window.tealium_instance,
    collectDispatchURL : "https://collect.tealiumiq.com/vdata/i.gif?tealium_account=your_account&tealium_profile=us-mobile"
});

Build Tips

If you have any issues building your app, you may need to remove and re-add the platform using the following Cordova command:

cordova platform rm <platform>
cordova platform add <platform>

Substitute “<platform>” for either “android” or “ios”.

This usually also resolves spurious XCode code signing errors when building for a physical device.

If you experience any trouble with CocoaPods when running your build, issue the command pod cache clean –all && pod repo update, which should clear your local CocoaPods cache.

Uninstall

To remove the Tealium plugin, run this command in your terminal:

cordova plugin rm tealium-cordova-plugin

Also be sure to remove the supplementary Tealium modules if installed (tealium-cordova-crashreporter,tealium-cordova-adidentifier,tealium-cordova-installreferrer).

Release Notes

See https://github.com/Tealium/cordova-plugin/blob/master/CHANGELOG.md for full list of changes.

Backwards Compatibility

The 1.1.0 release changed some API behavior. The following items in particular should be tested after upgrading:

If you were previously using theaddVolatile and addPersistent methods, please ensure that you are only storing supported data types specified above
On iOS, the plugin now runs most of its code on a background thread, except for the initialization method. This should not cause any issues, and should improve performance, but please test thoroughly and report any issues via the GitHub issues page.
The variable cordova_lifecycle, which was previously sent with all lifecycle events, has now been removed. If you still require this variable, you can create it again by using a Set Data Values extension in Tealium iQ, with a rule “if lifecycle_type is populated” to create the variable and add it to all lifeycle events.
On iOS, lifecycle sleep events are now tracked as soon as the user either puts the app into the background, or begins to close the app completely. This means when the user brings up the task switcher while an app is running by pressing the home button twice, a sleep event will be generated. If the user cancels the action and goes back into the app, a corresponding wake event will be generated. Previously, sleep events were only created when the user had finished backgrounding the app (by single-press of the home button, or switching to another app). This behavior matches the existing behavior on Android. Be aware that this may cause an increased amount of sleep events to be recorded in your analytics tools, but the numbers will be technically more accurate

Upgrade Notice

It is strongly recommended that you remove and re-add the plugin from your project for the 1.1.1 release.

In version 1.1.1, the plugin package name has changed from com.tealium.cordova.v5 to tealium-cordova-plugin.

To remove earlier plugin versions, you may need to issue the command:

cordova plugin rm com.tealium.cordova.v5