Tealium Learning Center

This is a separate, optional plugin that provides a Cordova wrapper for the native Android Crash Reporter module. iOS is not currently supported, but may be in a future release. Installation Navigate to your cordova app's directory in a terminal window, and enter  cordova plugin add tealium-cordova-crashreporter . No explicit initialization of this module is required; it is instantiated by the core Tealium plugin if the  isCrashReporterEnabled  parameter is set in the config object. Example: function tealiumInit(accountName, profileName, environmentName, instanceName){ tealium.init({ account : accountName , profile : profileName , environment : environmentName , instance : instanceName , isLifecycleEnabled: "true" , collectDispatchProfile:"cordova-demo" , isCrashReporterEnabled: "true" // enable crash reporting (uncaught exception handler) }); } Testing The JavaScript API exposes a method to force a crash to be triggered. In order to avoid accidental triggering of a crash in production, this method is hard-coded to work only if the following conditions are met: The environment is set to  dev Crash Reporter module is installed Crash Reporter module was successfully initialized. The variable  forceCrash  is present in the data layer If the above conditions are met, you may trigger a crash by issuing a tracking call containing the variable  forceCrash . Example: tealium.trackView({"forceCrash":"true"}); Removal To remove the Ad Identifier plugin, run  cordova plugin rm tealium-cordova-crashreporter . Also be sure to remove the  isCrashReporterEnabled  flag from the config object when initializing the main Tealium plugin. ... View more

This is a separate, optional plugin that provides a Cordova wrapper for the native Android Install Referrer module. Installation This feature is available as a separate npm package:  tealium-cordova-installreferrer . To install: Navigate to your cordova app's directory in a terminal window, and enter  cordova plugin add tealium-cordova-installreferrer . In the JavaScript file where you instantiate the main Tealium plugin, after calling tealium.init, add the following code: function tealiumInit(accountName, profileName, environmentName, instanceName){ var ir; tealium.init({...}); // check if installreferrer is installed and available ir = window.tealiumInstallReferrer; if (ir) { // init install referrer and store any received values as persistent data ir.setPersistent(instanceName); // Optionally, set as volatile data instead. Volatile data is cleared after the app is closed. Persistent data is therefore recommended // ir.setVolatile(instanceName); } } Testing Once the installreferrer plugin has been installed, you can test that it's working by manually triggering a system broadcast. Substitute  com.tealium.sample  with the RDNS bundle identifier for your app (unless testing with the Tealium sample app). > adb shell > am broadcast -a com.android.vending.INSTALL_REFERRER -n "com.tealium.sample/com.tealium.installreferrer.InstallReferrerReceiver" --es "referrer" "utm_source=mysource&utm_medium=mymedium&utm_term=myterm&utm_content=46b25e284dc36d5a7ef8f0e6b393febe3fcc8327&utm_campaign=mycampname" Removal To remove the Install Referrer plugin, run  cordova plugin rm tealium-cordova-installreferrer . To delete the Install Referrer data from persistent storage, call  tealium.removePersistent("install_referrer", <your tealium instance name>); ... View more

The Remote Command system allows you to control certain aspects of your app remotely using Tealium IQ. Starting in version 1.1.0 of the Cordova plugin, it's possible to register a JavaScript callback function with the Tealium plugin, which can then be called remotely from Tealium iQ whenever a specific set of load rules is satisfied. For example, you might wish to trigger a modal overlay in your Cordova app, which invites the user to participate in a survey when the user performs a specific function (completes a purchase, subscribes to emails etc.). The advantage of controlling this in Tealium iQ is that the text displayed in the modal overlay can be configured remotely, and additionally the overlay can be completely enabled/disabled via Tealium iQ without the need for an app release. You could also use Tealium iQ to hold config information for other 3rd party SDKs/plugins (e.g. API keys), which would give you the ability to quickly and dynamically change this information based on some information passed into Tealium iQ by a trackEvent or trackView call. For example, you could dynamically change API keys based on the Tealium environment currently loaded in the app (dev = XXXXXX, prod = YYYYYY). RemoteCommand Code Example // this code would normally be implemented in the main .js file for your app function tealiumInit(accountName, profileName, environmentName, instanceName){ tealium.init({ account : accountName // REQUIRED: Your account. , profile : profileName // REQUIRED: Profile you wish to use. , environment : environmentName // REQUIRED: "dev", "qa", or "prod". , instance : instanceName || window.tealium_instance // instance name used to refer to the current tealium instance , isLifecycleEnabled: "true" // explicitly enabling lifecycle tracking. Note string value required, not boolean // , collectDispatchURL:"https://collect.tealiumiq.com/vdata/i.gif?tealium_account=services-crouse&tealium_profile=mobile" , collectDispatchProfile:"demo" }); } function onDeviceReady() { // call our custom tealiumInit function tealiumInit("tealiummobile", "demo", "dev", "tealium_main"); console.log("onDeviceReady"); tealium.addRemoteCommand("getTIQMessage", window.tealium_instance, function (message){ // message is a JSON object containing mapped key-value pairs from TiQ if (message && message.message_text) { alert(message.message_text); } }); tealium.addRemoteCommand("getAnotherMessage", window.tealium_instance, function (message){ // message is a JSON object containing mapped key-value pairs from TiQ if (message && message.message_text) { alert(message.message_text); } }); // simple example to change the background color of the view to a color code returned from TiQ tealium.addRemoteCommand("changeBackgroundColor", window.tealium_instance, function (message){ // message is a JSON object containing mapped key-value pairs from TiQ if (message && message.bg_colorcode) { document.body.style.background = message.bg_colorcode; } }); } This example is also demonstrated in the TealiumSample app included on GitHub. Remote Commands Tealium iQ Config Prerequisite: Ensure you are using utag.js loader version 4.40 or above, or you may encounter issues with commands double-firing. Add the "TagBridge Custom Command" tag in Tealium iQ, and in the "Command ID" box on the tag config screen, enter the name of the command you wish to call, e.g. changeBackgroundColor Add any load rules you wish to associate with this command, e.g. "screen_title contains confirmation screen" Create a new variable in Tealium iQ called "app_background_color" or similar Add a new mapping from "app_background_color" to a destination of "bg_colorcode" in the "TagBridge Custom Command" tag In an extension, set the value of "app_background_color" to the desired Hex color code (e.g. #FFFF00 for yellow, hash/pound sign included). Once you have published your profile, and when your load rules are satisfied, the app background color will change to yellow. Idea: you could use a combination of setTimeout and cookies in a Tealium iQ JavaScript extension to fire your Remote Command after a delay, or only once within a given time period (e.g. 30 days). ... View more

Known Issues No known issues with the latest release Debugging the Tealium iQ and/or Cordova Webview Once the app is compiled, you can use the Safari Developer Tools for iOS and the Chrome Developer Tools for Android to remotely inspect the Tealium web view. For Chrome/Android, go to "chrome://inspect" and look for "mobile.html". For Safari/iOS, go to Develop -> <Your Device Name> -> "mobile.html". All network requests generated by the Tealium plugin will appear in the "Network" tab of the developer tools for each browser. You must connect your device with a USB cable to use this feature. Any errors logged during Tealium initialization will be stored on the global variable window.tealium_cordova_error. If Tealium init fails, check this variable in the JavaScript console (via Chrome or Safari) for error messages. Errors are stored here, because it is not always possible to inspect the app in time before the init occurs, so this method allows for later access to the error message. Remote debugging generally only works for debug/dev builds of your app. It is usually disabled for production builds General Advice 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" as appropriate. This usually also resolves spurious XCode code signing errors when building for a physical device. CocoaPods 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. ... View more

Parameters for JavaScript methods are given in the order the plugin expects them, e.g. for  function somefunction(a,b,c){} , the parameters  a,b,c  will be listed top to bottom in the following tables. Method:  init This function initializes the Tealium Cordova plugin Parameter Data Type Description/Usage config JavaScript Object* See separate table successCallback Function Overrides the default Success Callback to allow custom success handling errorCallback Function Overrides the default Success Callback to allow custom success handling *The  config  object Parameter Data Type Description/Usage Example Value account String Tealium Account Name "tealium" profile String Tealium Profile Name "main" environment String Tealium Environment Name "dev" instance String Arbitrary Tealium instance name "main" dataSourceId String Optional alphanumeric data source ID generated in UDH "3obb8c" isLifecycleEnabled String representation of Boolean (e.g. "false") Enables or disables automatic lifecycle tracking "false" logLevel Integer (Enum) Sets the log level of the Cordova plugin (does not affect core SDK log level). Defaults to tealium.logLevels.DEV if not specified. tealium.logLevels.DEV (Info, Warnings, Errors) tealium.logLevels.QA (Warnings, Errors) tealium.logLevels.PROD (Errors Only) tealium.logLevels.SILENT (No Logs) collectDispatchURL String Overrides the default Tealium Collect dispatch URL "https://collect.tealiumiq.com/vdata/i.gif?tealium_account=tealium&tealium_profile=mobile" collectDispatchProfile String Overrides the default Tealium Collect dispatch profile (default is always "main") "mobile" isCrashReporterEnabled String If set, enables the crash reporter module (default disabled) "true" Method:  trackView This function initiates a screen view tracking request to the Tealium Cordova plugin Parameter Data Type Description/Usage Example Value Data Object JavaScript/JSON object Populates the data layer for this tracking call with the key/value pairs specified {"screen_name": "Homescreen"} instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  trackEvent This function initiates an event tracking request to the Tealium Cordova plugin Parameter Data Type Description/Usage Example Value Data Object JavaScript/JSON object Populates the data layer for this tracking call with the key/value pairs specified {"event_name": "Click to call"} instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" track This function initiates a tracking request to the Tealium Cordova plugin Parameter Data Type Description/Usage Example Value Event Type String Tealium event type "link" (event) or "view" (screen view) Data Object JavaScript/JSON object Populates the data layer for this tracking call with the key/value pairs specified {"screen_name": "Homescreen"} instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  addPersistent This function adds data to the Tealium persistent data store Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be persisted "user_hashed_email" Value String or Array of strings The value to be persisted for this key "293c2529495b45cbbc7b451df5720e8c" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  addVolatile This function adds data to the Tealium volatile data store Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be stored in volatile memory "user_hashed_email" Value String or Array of strings, Object/Dictionary The value to be stored in volatile memory for this key "293c2529495b45cbbc7b451df5720e8c" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  removePersistent This function removes data from the Tealium persistent data store Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be removed from persistent storage "user_hashed_email" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  removeVolatile This function removes data from the Tealium volatile data store Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be removed from volatile memory "user_hashed_email" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  getPersistent This function retrieves a value from the Tealium Persistent data store Returns: Persisted data with the same data type that was originally stored (String or Array of strings) Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be retrieved from persistent storage "user_hashed_email" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  getVolatile This function retrieves a value from the Tealium Volatile data store Returns: Stored data with the same data type that was originally stored (String, Array of strings, or Object/Dictionary) Parameter Data Type Description/Usage Example Value Key Name String Key name of value to be retrieved from volatile storage "user_hashed_email" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Method:  addRemoteCommand This function adds a remote command for later execution, initiated by Tealium iQ Parameter Data Type Description/Usage Example Value Remote Command ID String ID of the remote command. Matching id must be used in Tealium iQ to trigger the code block "changeBackgroundColor" instance String Arbitrary instance name constant, used to refer to a specific tracking instance. "main" Code block Function A function literal or reference, which will be available for later remote execution from Tealium iQ function (message) { //do something} Method:  getVistorId This function returns the current Tealium visitor ID for the current user. It takes no parameters. Returns: String representation of the current visitor ID.   ... View more

This is a separate, optional plugin that provides a Cordova wrapper for the native Android Ad Identifier module, and additional code to get the iOS Advertising Identifier (IDFA). Installation Navigate to your cordova app's directory in a terminal window, and enter  cordova plugin add tealium-cordova-adidentifier . In the JavaScript file where you instantiate the main Tealium plugin, after calling tealium.init, add the following code: function tealiumInit(accountName, profileName, environmentName, instanceName){ var ai; tealium.init({...}); // check if installreferrer is installed and available ai = window.tealiumAdIdentifier; if (ai) { ai.setPersistent(instanceName); // Optionally, set as volatile data instead. Volatile data is cleared after the app is closed. Persistent data is therefore recommended // ai.setVolatile(instanceName); } } Testing After installing the plugin, the following variables will be available as additional parameters on all tracking calls. If you are sending your data to the Tealium UDH, you will see these variables in "EventStream > Live Events" or when running a Trace session. If you are using Tealium iQ only, you can create and map the variables to a tag of your choice, and you will be able to verify success by checking in your 3rd party tracking tools. The variables to look for are: Android ->  google_adid  iOS ->  device_advertising_id ,  device_advertising_vendor_id ,  device_advertising_enabled Removal To remove the Ad Identifier plugin, run  cordova plugin rm tealium-cordova-adidentifier . To delete the Ad Identifier data from persistent storage, call // android only tealium.removePersistent("google_adid", <your tealium instance name>); // ios only tealium.removePersistent("device_advertising_id", <your tealium instance name>); tealium.removePersistent("device_advertising_vendor_id", <your tealium instance name>); tealium.removePersistent("device_advertising_enabled", <your tealium instance name>);   ... View more

Tealium Collect By default, the core iOS and Android libraries send Tealium Collect data to the "main" profile in your Tealium account if you do not specify an alternative. The Cordova plugin allows you to override this behavior by passing one of two parameters in the config object: collectDispatchURL Example code below. See API Definition for more details function tealInit (accountName, profileName, environmentName, instanceName) { tealium.init({account : accountName, profile : profileName, environment : environmentName, instance : instanceName || window.tealium_instance , isLifecycleEnabled: "true" , collectDispatchURL:"https://collect.tealiumiq.com/vdata/i.gif?tealium_account="+accountName+"&tealium_profile="+profileName }); } collectDispatchProfile Example code below. See API Definition for more details. This is only effective if no value has been passed for the collectDispatchURL parameter. function tealInit (accountName, profileName, environmentName, instanceName) { tealium.init({account : accountName, profile : profileName, environment : environmentName, instance : instanceName || window.tealium_instance, isLifecycleEnabled: "true" , collectDispatchProfile:profileName }); } Automatic Lifecycle Tracking Automatic Lifecycle Tracking is generally a requirement for Adobe Analytics. If you do not need it, you can disable this feature by passing a string value of  "false"  for the  isLifecycleEnabled  parameter in the config object. See API Definition for more details function tealInit (accountName, profileName, environmentName, instanceName) { tealium.init({account : accountName, profile : profileName, environment : environmentName, instance : instanceName || window.tealium_instance, isLifecycleEnabled: "false" }); } Log Level This setting controls the amount of log output the plugin writes to the JavaScript console. If you do not pass an explicit value, the default setting depends on the current environment ("dev" ->  tealium.logLevels.DEV , "qa" ->  tealium.logLevels.QA , "prod" ->  tealium.logLevels.PROD ). Full description in API Definition function tealInit (accountName, profileName, environmentName, instanceName) { tealium.init({account : accountName, profile : profileName, environment : environmentName, instance : instanceName || window.tealium_instance, isLifecycleEnabled: "true", logLevel: tealium.logLevels.DEV }); } Crash Reporter This setting enables the Crash Reporter feature (currently Android only). This feature is disabled by default, and even if you enable it here, it will only become active once you have installed the separate Crash Reporter Plugin. function tealInit (accountName, profileName, environmentName, instanceName) { tealium.init({account : accountName, profile : profileName, environment : environmentName, instance : instanceName || window.tealium_instance, isLifecycleEnabled: "true", logLevel: tealium.logLevels.DEV, isCrashReporterEnabled: "true" // enable crash reporter on Android only }); } ... View more

General Concepts There are 2 main tracking methods available: trackEvent  is used to track any kind of user interaction, for example, a button click trackView  is used to track a transition to a new part of the app, for example, a new Activity in Android or new View in iOS. Especially if you are using Tealium iQ, it is important to make sure that you use the correct tracking call for the type of interaction you are tracking. Analytics tags in particular have a clear distinction between screen/page views and events, and using the wrong tracking method will interfere with this. The Data Layer The data layer is the list of key/value pairs you wish to track, which is passed to the tracking API as a plain JavaScript object. It is recommended to use a flat structure as much as possible, and avoid nesting unless absolutely necessary. Example Data Layer { "screen_title": "Product Listing Page", "product_price" : ["79.99", "25.00"], "product_name" : ["Pink Table Lamp", "Baseball Cap"], "product_sku" : ["ABC123", "DEF345"], "screen_category" : "Product Listing", "user_name": "janedoe123", "user_isregistered": "true" } At least two of these pieces of information,  user_name  and  user_isregistered  are probably going to change very infrequently, and as such, it may not be convenient to send them manually with every hit. If this is the case, you have the option to use the  addVolatile  and/or  addPersistent  API methods, which will automatically add the specified data to every event, saving the trouble of manually specifying the data every time you call the tracking methods. Tracking Screen Views This is the basic code required to track a screen view // arguments - data object, instance name tealium.trackView({"screen_name": "Homescreen"}, "main"); Tracking Other Events This is the basic code required to track an event // arguments - data object, instance name tealium.trackEvent({"event_name": "Buy Now Clicked"}, "main"); Sending data with every hit Some variables may be required on every hit generated by an app (e.g. user id). To save having to manually add this data to every hit, the Cordova plugin gives you the option to store the data as either "volatile" (deleted at app termination), or "persistent" (stored permanently until manually deleted). From the point the data is added, it will be appended to every hit, including lifecycle hits. For additional information, see API Definition. Code examples: tealium.addPersistent("<keyname>", "<value>", window.tealium_instance);  Adds a persistent variable named <keyname> with value <value> to the persistent data store tealium.removePersistent("<keyname>", window.tealium_instance);  Removes a persistent variable named <keyname> from the persistent data store tealium.addVolatile("<keyname>", "<value>", window.tealium_instance);  Adds a volatile variable named <keyname> with value <value> to the persistent data store tealium.removeVolatile("<keyname>", window.tealium_instance);  Removes a volatile variable named <keyname> from the volatile data store Retrieving values from persistent/volatile storage If you wish to check the contents of an existing volatile/persistent data variable previously stored via the  addPersistent  or  addVolatile  API methods, you can do so using the following methods.For additional information, see API Definition. tealium.getPersistent("<keyname>", window.tealium_instance, callback);  Retrieves a persistent data source named from the persistent data store, and then passes the value into the callback function passed in the 3rd parameter tealium.getVolatile("<keyname>", window.tealium_instance, callback);  Retrieves a persistent data source named from the persistent data store, and then passes the value into the callback function passed in the 3rd parameter Notes: These methods will return  null  on the JavaScript side if the requested data could not be found The returned value could be any of the supported data types listed above. You should therefore add a safety check to ensure that the returned data is of the expected datatype before performing any operations on it (e.g. check that a value expected as an array is really an array before trying to use the Array.push prototype method) Example: // retrieves a volatile variable called "myvolatilevariable" tealium.getVolatile("myvolatilevariable", window.tealium_instance, function (val) { // this callback will be called when the volatile data source has been found if (val === null) { // returns null if data was not found alert("Requested volatile data could not be found"); } else { alert("Volatile object data returned: " + "myvolatilevariable = " + val.toString()); } });     ... View more

The Tealium Cordova plugin provides the means to integrate iQ Tag Management and Tealium's suite of Universal Data Hub products into a Cordova application.  Installation Notes Requirements cordova-cli@7.0.0 * *May function with earlier Cordova versions, but this has not been tested Embedded Tealium Libraries Tealium iOS 5.3.2 including lifecycle module (installed via CocoaPods) Tealium Android 5.4.2 including lifecycle module (installed via Gradle/Maven) 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 therefore need to issue the command: cordova plugin rm com.tealium.cordova.v5 Dependency Management As of version 1.1.1 of the Tealium Cordova plugin, framework files are no longer directly shipped with the plugin. Instead, CocoaPods is used for iOS, and Maven for Android. This reduces the size of the plugin and makes ongoing updates much easier. This also removes the need for having a separate build for iOS for Simulator and Device builds, and manually editing your Xcode project to add the Tealium frameworks to "Embedded Binaries" is no longer required. This should result in a much simpler deployment process, and should play nicer with automated build processes, such as Phonegap Build. If you do not already have CocoaPods installed, you will need to follow this guide: https://guides.cocoapods.org/using/getting-started.html  Installation Methods NPM Installation It is recommended to install the plugin via NPM. 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 Installation If you cannot use NPM, you may install the plugins manually. From the Command Line Interface (CLI), first: cd in to project cordova platform add <PLATFORM> cordova plugin add </LOCAL_PATH_TO_TEALIUM_PLUGIN/> cordova build <PLATFORM> Cordova Derivatives This plugin should work fine on all Cordova derivatives, such as PhoneGap, Ionic, Onsen UI, Monaca, and many more.    Initializing The Plugin tealium.init({ account : "tealiummobile" // CHANGE REQUIRED: Your account. , profile : "demo" // CHANGE REQUIRED: Profile you wish to use. , environment : "dev" // CHANGE REQUIRED: Desired target environment - "dev", "qa", or "prod". , instance : "tealium" // CHANGE OPITONAL: This is the instance name you will use to refer to your tracker once created. , isLifecycleEnabled : "true" // CHANGE OPTIONAL: If you wish to disable lifecycle tracking (launch, wake, sleep), set this value to STRING false (not boolean false) , isCrashReporterEnabled: "true" // CHANGE OPTIONAL: Remove this or set to "false" to disable crash reporting on Android , logLevel: tealium.logLevels.DEV // CHANGE OPTIONAL: Manually set the required log level for JavaScript }); Lifecycle tracking is enabled by default if you do not pass any value for isLifecycleEnabled. You must pass the string value "false" to disable lifecycle tracking. Please see API Definition below for additional initialization parameters. The "instance" Argument In previous versions of the plugin (pre 0.9.6), only a single instance of Tealium was supported. In the current version, multiple instances of Tealium can be created. The new plugin therefore requires an instance ID to be passed at initialization time, and with each subsequent tracking request. If you are upgrading, you will therefore need to modify your code to specify a tracking instance. If you only require a single instance, it is recommended to create a global variable to store your instance ID, and pass this variable on each tracking call. An example of this is shown in the sample app. Removing The Plugin If you need to remove the Tealium plugin completely, 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 ). 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 the  addVolatile  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, or via support@tealium.com 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 Release Notes See https://github.com/Tealium/cordova-plugin/blob/master/CHANGELOG.md for full list of changes. ... View more

A common problem with mobile apps is trying to figure out how your effective marketing spend for acquisition is. For example, you may spend money with ad networks for promoting your app, but have no idea how many of these ads leads to successful download and opening. Uniquely on Android, the operating system provides a handy way to identify where the user downloaded your app from, and this information can be gathered by your app and passed to any third party analytics tool. In this article: Table of Contents Placeholder How Can Tealium Help? To take the burden away from your app developers, Tealium has built a module that integrates with our standard Android library (version 5.2+), that automatically collects the referrer information when available, and makes the data available as a standard variable for you to use with your tags. Adding the Google Play Install Referrer Dependencies Google Play Install Referrer API Option 1: Manually Add Dependency Use the following steps to manually add the Google Play Install Referrer: Download the   tealium.installreferrer-1.1.1.aar  file from the following URL: https://github.com/Tealium/tealium-android/tree/master/Support/InstallReferrer In the project's root build.gradle  file, ensure that you have the following: allprojects { repositories { jcenter() flatDir { dirs 'libs' } } } Include in your app's "libs" directory, and add the following to your project module's build.gradle: dependencies { implementation(name:'tealium-5.5.4', ext:'aar') // only required if you do not already have this reference implementation(name:'tealium.installreferrer-1.1.1', ext:'aar') implementation(name:'tealium.lifecycle-1.1.2', ext:'aar') // only required if you do not already have this reference and require lifecycle tracking } Option 2: Add as a Maven Repository Dependency Use the following steps to add the Google Play Install Referrer using a Maven repository: In your project's root gradle file, add the following maven repository: maven { url "http://maven.tealiumiq.com/android/releases/" } In your project module gradle file, add the following maven dependency: dependencies{ implementation 'com.tealium:library:5.5.4' //only required if you do not have this reference implementation 'com.tealium:installreferrer:1.1.1' implementation 'com.tealium:lifecycle:1.1.2' //only required if you do not already have this reference and require lifecycle tracking } In the same block where you instantiate the Tealium library (after instantiating Tealium), add the following calls: // import the Tealium InstallReferrer module in the import section import com.tealium.installreferrer.InstallReferrerReceiver; … // substitute the example instance name here with the same instance name you used when initializing the Tealium library private static final String TEALIUM_INSTANCENAME = "teal"; // call this to store the referrer as Persistent data - recommended InstallReferrerReceiver.setReferrerPersistent(getApplicationContext(), TEALIUM_INSTANCENAME); // call this to store the referrer as Volatile data (reset at app restart/terminate) - not recommended in most cases InstallReferrerReceiver.setReferrerVolatile(getApplicationContext(), TEALIUM_INSTANCENAME); Data Layer Variables Variable Description Type Example   install_referrer Referral URL String "https://tealium.com/mobile/install"  install_referrer_begin_timestamp Timestamp when referrer click happens (seconds) long  1544410817  install_referrer_click_timestamp   Timestamp when installation begins (seconds) long  1544466843 Deleting the Stored InstallReferrer Information (Not typically required) To delete the stored install referrer string, you can call the standard methods provided by the Tealium library to remove variables from persistent or volatile storage. The key name for the variable is exposed by the InstallReferrerReceiver class. The following example  shows how to remove the stored install referrer from both persistent and volatile data. This code will have no effect and will not caise an errorif the variable doesn't already exist. // import the Tealium InstallReferrer module in the import section import com.tealium.installreferrer.InstallReferrerReceiver; … private static final String TEALIUM_INSTANCENAME = "teal"; final Tealium instance = Tealium.getInstance(TEALIUM_INSTANCENAME); // remove from persistent data store instance.getDataSources().getPersistentDataSources().edit().remove(InstallReferrerReceiver.KEY_INSTALL_REFERRER).apply(); // remove from volatile data store (session only) instance.getDataSources().getVolatileDataSources().remove(InstallReferrerReceiver.KEY_INSTALL_REFERRER); Example Code Snippet for Tealium SDK v4 This module is only compatible with Tealium SDK v5.X. If you are still using v4.X and require this functionality, see below for a code example // Android Manifest <receiver android:name="com.tealium.InstallReferrerReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL\_REFERRER" /> </intent-filter> </receiver> // Class for retrieving install referrer public class InstallReferrerReceiver extends BroadcastReceiver { private static final String INSTALL\_REFERRER = "INSTALL\_REFERRER"; public void onReceive(Context context, Intent intent) { if (intent != null) { return; } Bundle extras = intent.getExtras(); if (extras == null) { return; } String referrer = extras.getString("referrer"); if (StringUtils.isNotBlank(referrer)) { Tealium.getGlobalCustomData().edit().putString(INSTALL\_REFERRER, referrer).apply(); } } } Caveats and Warnings Be aware that the Tealium InstallReferrer module implements the Google Play Install Referrer API. Per Google's recommendations, the API should only be invoked once during the very first install execution. You can have your app register to the system broadcast  Intent.ACTION_PACKAGE_FIRST_LAUNCH  to identify the app's first launch event. Additionally, install referrer information is available for 90 days and does not change unless the app is reinstalled. Vendor Resources For additonal information, see the following vendor resources: Andrioid Play Install Referrer API Overview Android Quick Start AppsFlyer SDK Integration - Android Testing the Google Play Install Referrer ... View more

This article describes how to set up the Adobe Analytics connector in your Customer Data Hub account. In this article: Table of Contents Placeholder Introduction The Adobe Analytics Connector in the Tealium Customer Data Hub uses Adobe's Data Insertion API to send analytics data server-side, in place of using the JavaScript beacon on a web page or mobile app. This reduces the amount of data transmitted from the client-side, and also offers the advantage of being able to pass audience and visitor data from EventStream or AudienceStream to Adobe Analytics. Connector Actions Action Name AudienceStream EventStream Send Analytics Event ✓ ✓ Connector Configuration Use the following steps in the interface to configure the Adobe Analytics connector: Go to the Connector marketplace and add the Adobe Analytics connector. Read the Connector Overview article for general instructions on how to add a connector. In the Title field, enter a title for the connector. In the Data Insertion Domain field, enter the domain for your Adobe Analytics data collection servers. For example, namespace.122.2o7.net . In the Report Suite ID field, enter your Report Suite ID. This is the Report Suite used to submit the data. To send data to multiple destinations use a comma-separated list of report suites. This value can also be set with a data mapping. In the Notes field, enter any relevant notes about this connector. Click Next. You are now on the Actions tab. From the Actions drop-down list, select "Send Analytics Event" from the drop-down list and configure the following parameters: Group Description Event Parameters See "General Attributes" below Auto-mapping of Lifecycle Event Attributes for Mobile Data-sources Check this checkbox to automatically map values from the Event Parameters section to Adobe data elements. Auto mapping only applies to Mobile EventStream App Lifecycle only. For more information see Adobe Analytics Connector Lifecycle Mappings Context Data Specify keys using the dot format. For example "my.a". Multiple key-value pairs can be specified. eVars Specify the event eVars by mapping an attribute to a number. For example: Map event_count to 1 for eVar1. Valid range is 1 through 100, 250 for Premium Accounts Hierarchy A hierarchy string. Select from 1 through 5. List A list of values that are passed into a variable, then reported as individual line items for reporting Select from 1 through 3. Requires Array type in data layer. Tealium will format the data correctly to be passed along Properties Analytics property name. Specify the name by mapping an attribute to a number. For example: Map lifetime_value to 1 for prop1. Events Specify a list of events, or a comma-separated custom value. see Adobe Analytics Configure Events Implementation Event Mapping Map a potential value contained in the Events Array (configured above) to the Adobe Analytics Custom Event name. For example, registration to event3 would replace "registration" with "event3" in the event payload. Event Values Specify values for Counter , Numeric , and Currency events. To specify an event, use a number. As an example, 1 will be sent over as event1 . Products Specify product attributes (Id, Category, Quantity, Price) All arrays must be equal-sized and order-aligned For additional information, see Adobe Analytics Product Implementation Product eVars Specify product eVars values. All arrays must be equal-sized to those in the Product section. Empty values will be ignored. Specify eVar mappings with a number. As an example, 1 will be mapped to eVar1 . Product Events Specify product event values. All arrays must be equal-sized to those in the Product section. Empty values will be ignored. Specify event mappings with a number. As an example, 1 will be mapped to event1 . Click Save. Save and Publish your changes. General Attributes For a full reference of all attributes, including details on exactly what each field should contain, see Adobe's API documentation and the Visitor & Experience Cloud IDs section of this article. Report Suite IDs Specify a report suite ID, which will override any value previously entered in the Connector Configuration UI. If you do not need to override that value, you can leave this field blank. You can use either a data layer variable, or a "Custom Value". If you wish to send data to multiple report suites, you may use a comma-separated list. This will overwrite the value defined in the Configuration Tab Specifies the report suites where you want to submit data. Contained in the URL If specifying Data Layer attributes, use simple attribute types per row. We will format the data correctly to be passed along Map From Map To Notes Sample Connector Output Customer Data Hub attribute containing a persistent visitor ID, e.g. tealium_visitor_id visitorID* Ensure that this is a visitor-level persistent value. Example: Tealium Visitor ID <visitorID>01619ea9a91a001af7e29b75797104079005c07101008M</visitorID> Customer Data Hub attribute containing a page name/title pageName String value <pageName>Homepage</pageName> Customer Data Hub attribute containing the current URL (e.g. built-in "Current URL" attribute) pageURL String value <pageURL>http://www.tealium.com</pageURL> Customer Data Hub attribute containing the Adobe Experience Cloud ID marketingCloudVisitorID* Usually retrieved via the Visitor API JavaScript tag. Implemented in iQ Tag Management. <marketingCloudVisitorID></marketingCloudVisitorID> Customer Data Hub attribute containing the link name linkName String value. Example: tealium_event <linkName>Buy Now</linkName> Customer Data Hub attribute containing the URL of the link clicked linkURL String value <linkURL>https://www.tealium.com/products/widgets/buynow\</linkURL> Customer Data Hub attribute containing the order ID purchaseID String value. E-commerce Order ID <purchaseID>ORD12345</purchaseID> Customer Data Hub attribute containing the document referrer referrer Recommend using built-in "Referring URL" attribute. <referrer>https://www.tealium.com/shop\</referrer> Customer Data Hub attribute containing the timestamp from the time the event occurred timestamp Optional. Unix epoch seconds or ISO-8601 format. Do not map if your report suite is not explicitly configures to accepts timestamped hits. For more information, see the Timestamp Implementation Guide. <timestamp>1519207951063</timestamp> Customer Data Hub attribute containing the IP address of the visitor ipaddress To use this optional attribute, you must have enabled the Visitor IP attribute in your account. Contact your account manager if you need this feature. <ipaddress>127.0.0.1</ipaddress> Customer Data Hub attribute containing the user agent of the browser/device userAgent Recommend using the built-in User Agent attribute in Customer Data Hub <userAgent>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.167 Safari/537.36</userAgent> Customer Data Hub attribute containing the transaction ID for a custom event (not order ID) transactionID This is not the same as purchaseID. See the Adobe Analytics documentation for details. <transactionID>CMPSUMMER18</transactionID> Link Type This field is used for link tracking, and allows setting of a Link Type. Map From Map To Description Example Sample Connector Output Select any attribute from the drop-down list or enter custom value Link type: "d" - Download Link "e" - Exit Link "o" - Custom (other) Link Sends a Link Type to Adobe Analytics only if the attribute selected has a value* Map: (Custom Value): "true" to "o" <linkType>o</linkType> If the attribute selected has a value of null , undefined or "" (empty string), the Link Type will not be set on the outgoing request. Context Data Context Data may be used as a more user-friendly alternative to props and eVars. You can map any event attribute or visitor attribute to Context Data variables in Adobe Analytics. Context Data variables may have any name, but is is an Adobe best practice is to prefix all variables with a unique key, such as your company name. Some variables are reserved and may only be used for predetermined functionality, such as Lifecycle Metrics; these variables are prefixed with " a. ". Map From Map To Description Example Sample Connector Output Select any attribute from dropdown, or enter custom value companyname.someproperty Maps a defined Customer Data Hub attribute to a Context Data attribute Map: (Customer Data Hub Attribute) Campaign Name to "tealium.productColor" <contextData><tealium.productColor>Red</tealium.productColor></contextData> Analytics eVars This field is used to map Customer Data Hub attributes to eVars. eVars must be specified using the word "eVar" (not case-sensitive), plus the number of the eVar, e.g. "eVar11". Valid range is 1 through 250. Map From Map To Description Example Sample Connector Output Select any attribute from dropdown, or enter custom value eVarX, where X is an integer in the range 1 - 250 Maps a defined Customer Data Hub attribute to an eVar in your analytics reports Map: (Customer Data Hub Attribute) Campaign Name to "eVar75" <eVar75>Summer2018</eVar75> Analytics Property Name (s.props) This field is used to map Customer Data Hub attributes to props. Props must be specified using the word prop , plus the number of the prop, e.g. "prop4". Valid range is 1 through 75. List props are supported, but these require prior configuration in your Adobe Analytics Report Suite admin interface. Map From Map To Description Example Sample Connector Output Select any attribute from dropdown, or enter custom value propX, where X is an integer in the range 1 - 75 Maps a defined Customer Data Hub attribute to an prop in your analytics reports Map: (Customer Data Hub Attribute) Link Name to "prop4" <prop4>Buy Now</prop4> Events (s.events) Events allow you to measure how frequently a particular event is occurring on your website or in your app. The events variable is a comma-separated string listing all the events that should be counted for a particular analytics event. Both predefined events and custom events are sent in the same string. In the Adobe Analytics connector, the following two methods are used to specify events: Map an array value containing a list of event names that has been populated elsewhere (e.g. an extension in iQ Tag Management, an Enrichment, or directly in your data layer). Map From Data Type Example Input Sample Connector Output Customer Data Hub attribute representing a list of events Array ["event1", "event5", "event9"] <events>event1,event5,event9</events> Specify an array of string values which map to specific event numbers, and specify the event number mappings in the "Custom Event Mapping" section as follows: Map From Map To Example Event Array Example Input Sample Connector Output Custom text value containing a string to look up in the Events array Name of event to trigger, e.g. event8 ["newsletter_registration", "homepage_viewed"] "newsletter_registration" <events>event8</events> (because string "newsletter_registration" appeared in the events array) Event Value Mapping This field allows numerical values to be assigned to events. This field is not correlated to the "Custom Event Mapping" field; that is, if "event2" is specified in the "Custom Event Mapping" and is also specified as a "Value" event, it would be included in the event variable twice - once with no value, and once with. Map From Data Type Map To Example Input Sample Connector Output Attribute representing a numerical value Number eventX, where X is the number of the event Map "9" to "event5" <events>event5=9</events> Event Serialization Configure event serialization by mapping an attribute that contains the event ID to a number that specifies the event. For example, mapping "ABC123" to "2" sends "event2=ABC123". Map From Data Type Map To Example Input Sample Connector Output Attribute representing an event ID String The event number Map "ABC123" to "1", Map "ABC123" to "2" <events>event1=ABC123,event2:ABC123</events> Products The Products variable is used wherever it is necessary to capture e-commerce information about one or more products on a particular page (Category, Product ID, Price, Quantity). Only Customer Data Hub attributes with Array data types may be used to populate the Products variable. All arrays must be equal in length (i.e. if there are 5 products on the page, Product ID, Quantity, Price, and Category must all be 5 elements in length). Map From Data Type Map To Example Input Data Sample Connector Output Customer Data Hub attribute representing Product Category Array Products Category ["Shoes", "Shirts"] <products>Shoes;;;,Shirts;;;</products> Customer Data Hub attribute representing Product ID Array Products ID ["ABC123", "EFG234"] <products>;ABC123;;,;EFG234;;</products> Customer Data Hub attribute representing Quantity Array Products Quantity ["1", "2"] <products>;;1;,;;2;;</products> Customer Data Hub attribute representing Price Array Products Price ["149.99", "79.80"] <products>;;;149.99,;;;79.80</products> Product Event Value Mapping This field allows a custom conversion event to be assigned to each product in the Products variable, and a numerical value to be assigned to each event. If a "simple" variable is mapped (singular value, or custom text value), then the same value is applied to all products in the list. If a list (array) value is mapped, then the array must have the same length as the rest of the product arrays, and each item in the array will have a different value (according to its position in the array). For these examples, assume the following product arrays are present as event attributes: Product Category: ["Footwear", "Apparel"] Product ID: ["Running Shoes", "T-Shirt"] Quantity: ["1", "1"] Price: ["99.99", "49.99"] Map From Data Type Map To Example Input Value Sample Connector Output Custom text value containing a numerical value String Name of event to trigger, e.g. event8 "9.99" (custom value) <events>event8</events><products>Footwear;Running Shoes;1;99.99;event8=9.99,Apparel;T-Shirt;1;49.99;event8=9.99</products> Customer Data Hub attribute representing array of numerical data Array Name of event to trigger, e.g. event12 ["1.99", "4.99"] <events>event8</events><products>Footwear;Running Shoes;1;99.99;event12=1.99,Apparel;T-Shirt;1;49.99;event12=4.99</products> Product Merchandising eVars This field allows eVars to be assigned to each product in the Products variable. These work in the same way as the "Product Event Value Mapping" field, detailed above. Map From Data Type Map To Example Input Value Sample Connector Output Custom text value containing an eVar value String Name of eVar to trigger, e.g. eVar4 "my_custom_value" <products>Footwear;Running Shoes;1;99.99;event8=9.99;eVar4=my_custom_value,Apparel;T-Shirt;1;49.99;event8=9.99;eVar4=my_custom_value</products> Customer Data Hub attribute representing array of eVar values (e.g. Product Color) Array Name of eVar to trigger, e.g. eVar6 ["red", "green"] <products>Footwear;Running Shoes;1;99.99;event8=9.99;eVar6=red,Apparel;T-Shirt;1;49.99;event8=9.99;eVar6=green</products> Hierarchy Data Page Hierarchy helps to classify a page within your site/app's navigation structure. There are five (5) available slots: hier1 - hier5. The only supported Customer Data Hub attribute type that can be used as a hierarchy var is an Array. Map From Data Type Map To Description Example Sample Connector Output Select any attribute from dropdown, or enter custom value Array hier1 - hier5 (drop-down selection) Maps a defined Customer Data Hub attribute in Array format to a specified hierarchy var in Adobe Analytics Map: (Customer Data Hub Attribute) Page Classification to "hier1" <hier1>Article</hier1> List Data List Variables are delimited strings containing multiple values, and are often used for attribution purposes. A maximum of 3 list variables is available for each Report Suite. The only supported Customer Data Hub attribute type that can be used as a list var is an Array. Map From Data Type Map To Description Example Sample Connector Output Select any array attribute from dropdown Array list1, list2, list3 (dropdown selection) Maps a defined Customer Data Hub attribute in Array format to a specified list var in Adobe Analytics Map: (Customer Data Hub Attribute) Referrer List to "list1" <list1>google.com</list1> Visitor and Experience Cloud IDs See the Adobe Analytics documentation on Visitor IDs, and the order of preference in the event that multiple IDs are provided. Use Case 1: No prior Adobe Analytics implementation If this will be a brand new Adobe Analytics implementation, 100% server-side, you may use your own unique visitor ID, and pass it to the visitorID attribute in the connector. You will need to decide what constitutes a suitable visitor ID, within the constraints set out by Adobe. Use Case 2: Migrating from existing Adobe Analytics client-side JavaScript If you are migrating from a JavaScript-based Adobe Analytics tag to the server-side connector, you will need to keep a consistent visitor ID to avoid "losing" visitors when/if you migrate fully. You will also need to migrate the visitor IDs if you are implementing the Adobe Analytics Customer Data Hub connector as a secondary collection mechanism (where you are still using the JavaScript tag on your web pages or in your apps as the primary collection mechanism). Use the following steps to migrate from existing Adobe Analytics client-side JavaScript, as described in this use case: Follow these instructions to configure the Adobe Experience Cloud ID tag and set up the tag in iQ Tag Management. In this step, you will store the Adobe visitor IDs in a first-party cookie. This will ensure that the value is transmitted to the Customer Data Hub on each hit, without needing to re-request the value for the duration of the session. In iQ Tag Management, go to the Data Layer tab, and create two (2) new First Party Cookie variables called utag_main_adobe_mcid and utag_main_aa_vid . You may rename these variables if you wish, but be sure to retain the "utag_main_" prefix, which will save cookie space by stacking into the utag_main cookie. If you rename the variables, you will need to also update the JavaScript snippet below Create a new JavaScript Code extension, scoped to the Adobe Experience Cloud ID Service tag, and paste in the following code: if (typeof vAPI !== "undefined") { vAPI.getInstance(u.data.adobe_org_id, function (visitor) { var mcID = visitor.getMarketingCloudVisitorID(), analyticsID = visitor.getAnalyticsVisitorID(), sessionExpiry = ";exp-session"; // store Adobe IDs for the session duration if (!mcID) { // something went wrong - the visitor IDs could not be retrieved utag.DB("MCID could not be returned"); } else { utag.loader.SC("utag_main",{"adobe_mcid" : mcID + sessionExpiry, "aa_vid" : analyticsID + sessionExpiry}); // optionally, trigger an empty utag.link call to trigger sending the cookie values to UDH // if utag.track call is omitted (default), values will be sent on the next utag.link or utag.view call anyway // utag.track is used to avoid calling other 3rd party tags; only the collect tag should respond // utag.track("adobe_vid_updated", {}); } }, u.clearEmptyKeys(u.data.config), u.data.customer_ids); } This creates a callback to the Adobe Visitor ID service which will be called when the visitor ID(s) have been successfully retrieved from Adobe's servers, and stores the Visitor ID and Experience Cloud ID in Tealium's own first-party cookie (utag_main). The cookie will expire at the end of the session in case the Visitor ID gets updated in future. If you wish to make the cookie persistent (non-expiring), you could set sessionExpiry to "" in the above code. Add a condition to the JavaScript extension "utag_main_adobe_mcid is not defined AND utag_main_aa_vid is not defined ". This prevents the code from running again during this session. Configure the Customer Data Hub for AudienceStream and EventStream. AudienceStream Configuration If you have AudienceStream, you may store the Adobe Visitor ID and Experience Cloud ID as visitor-level string attributes. Do not store them as Visitor ID attributes. For any actions triggered by an audience event, you may then map the new attribute to visitorID and marketingCloudVisitorID in the connector configuration. EventStream Configuration If you only have EventStream, you do not have the ability to store visitor ID variables, which is why we stored the value in a cookie. If you have already published your iQ Tag Management configuration from the previous step to Prod, you will find the new utag_main_adobe_mcid and utag_main_aa_vid values already present in your Event Attributes. If you have not published to Prod, you may manually add the event attributes, using the First Party Cookie string attribute type. Once you have defined these attributes, you may now choose them in the Adobe Analytics connector and map them to marketingCloudVisitorID and visitorID , respectively. Debugging Common Issues To test the connector, we recommend using the Trace tool. While running a trace, look for the "HTTP Request Body" field, which will show the formatted XML that was sent to Adobe. You can compare the XML output to the "Sample Connector Output" fields in the above tables to verify the output. Look for any errors in the response code being returned from Adobe. Anything other than HTTP Response Status: 200/Successful indicates that there was an error with the request. The full URL structure for the Data Insertion API follows the format http://namespace.112.2o7.net/b/ss//6 . Note that the double forward slash is intentional and valid (in the JavaScript Adobe Analytics implementation, the Report Suite ID would reside here). /6 indicates that an XML payload is being transmitted, and the reportSuite value is sent as part of the XML payload. This is the value you will see when running a Trace session. You do not need to enter the full URL value into the connector configuration; Tealium auto-generates the URL based on the Data Insertion Domain value. You will only see the full URL when running a Trace session. For your specific implementation, you may have a different value for the Data Insertion Domain (e.g. sc.omtrdc.net ), but the namespace should always precede the domain (e.g. namespace.sc.omtrdc.net ), except where you have your own first-party tracking domain (e.g. smetrics.acme.com ). ... View more