Tealium Technical Implementation Guide 4.39 - Magento...events: utag.view() and utag.link(). Each...

Tealium Technical Implementation Guide | © 2016 Tealium, Inc. All rights reserved. 2

Table of Contents

Summary .................................................................................................................................. 3!Universal Tag (utag.js) ............................................................................................................. 3!Asynchronous vs. Synchronous ........................................................................................................ 3!Tealium Tools .................................................................................................................................... 4!

Web Companion ........................................................................................................................... 4!Universal Tag Monitor .................................................................................................................... 4!

Data Layer Design .................................................................................................................... 5!Universal Data Object (UDO) ............................................................................................................. 5!Page Types ....................................................................................................................................... 6!Product Arrays .................................................................................................................................. 7!Tracking Functions .................................................................................................................. 8!utag.view() ......................................................................................................................................... 8!

Page View Tracking ....................................................................................................................... 8!Single Page Applications ............................................................................................................... 8!

utag.link() .......................................................................................................................................... 9!Dynamic Event Tracking ................................................................................................................ 9!

Triggering Specific Tags .................................................................................................................. 10!Event Tracking: Understanding Your Options .................................................................................. 10!

Option #1 - jQuery Extensions ..................................................................................................... 11!Option #2 - Coded utag.link, utag.view ........................................................................................ 11!Option #3 - Page UDO ................................................................................................................ 12!Option #4 - Video ........................................................................................................................ 13!Event Tracking Options Summary ................................................................................................ 13!

Full Page Example Code ....................................................................................................... 14!Appendix ................................................................................................................................ 15!

A. Page Performance and utag.js ................................................................................................ 15!B. Sample Data Layer .................................................................................................................. 15!

Tealium Technical Implementation Guide | © 2016 Tealium, Inc. All rights reserved.

Tealium is the leader in enterprise tag management, a new class of application that enables digital marketers to more easily deploy their mission-critical online solutions, while also providing a hub for managing and exchanging digital data.

Summary This document provides instructions for implementing the Tealium Universal Tag on your website. Included are details about the Tealium code snippet, data layer best practices, and options for dynamic event tracking.

Universal Tag (utag.js) The Tealium tag is a JavaScript library that replaces third-party tags with a single snippet of code placed after the opening <body> tag on your page (or as high on the page as possible). The utag.js file contains all of the generated code necessary to load third-party tags onto your site.

The path to the utag.js file comprises the following attributes:

• Account: the name of your account in Tealium iQ • Profile: the name of the profile in Tealium iQ ("main" is the default) • Environment: one of three default publish environments: dev, qa, or prod (or custom)

Asynchronous vs. Synchronous Tealium's best practice is to use asynchronous loading for all tags and vendor code. This ensures that Tealium (or other third-party vendors) will not interfere with the loading of your web content, which provides an overall better user experience for visitors to your site. The Tealium code is designed to be placed within the <body> tag of the page (as opposed to the <head>). This

<script type="text/javascript"> (function(a,b,c,d){ a='//tags.tiqcdn.com/utag/[ACCOUNT]/[PROFILE]/[ENV]/utag.js'; b=document;c='script';d=b.createElement(c);d.src=a; d.type='text/java'+c;d.async=true; a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a) })(); </script>


positioning provides the best compatibility with the greatest number of vendors and allows third-party tracking to complete before the visitor navigates to the next page.

For more information about asynchronous vs. synchronous see the Appendix.

Tealium Tools Tealium offers a powerful extension for the Chrome browser called Tealium Tools. This extension exposes a variety of essential tools to help manage your Tealium implementation, including quick access to Tealium iQ, TLC (Learning Community), Scan Companion, and many others. Install Tealium Tools extension for Chrome browser.

Web Companion Web Companion is a browser tool for validating the Universal Tag on your website. It provides easy access to extend the data layer and offers advance event tracking options such as adding custom click tracking to a page. More Info

Universal Tag Monitor The Universal Tag Monitor provides an easy way to validate the UDO and tracking events occuring on your site. Once launched, it will display the UDO detected on each page you visit as well as in-page events that are tracked within utag.js. More info

https://chrome.google.com/webstore/detail/tealium-tools/gidnphnamcemailggkemcgclnjeeokaa?hl=en-US

https://community.tealiumiq.com/t5/Developers/Web-Companion/m-p/1671

https://community.tealiumiq.com/t5/Developers/Tealium-Universal-Tag-Monitor/m-p/10755


Data Layer Design The data layer is the foundation of your Tealium solution and will serve as the one true definition of your data across all digital assets and customer interactions. The data layer comprises all of the various data elements that will be collected across your site and the visitor interactions and events that will be tracked.

Universal Data Object (UDO) The primary component of the data layer is the Universal Data Object (UDO). The UDO is a JavaScript object literal called "utag_data" in which data from your webpage is passed to the Tealium tag. The properties in this object are named using plain-English, vendor neutral terms that are tailored to your business.

Note: The UDO should be defined and populated prior to loading the Universal Tag.

UDO Technical Guidelines When implementing the UDO there are certain guidelines to follow, not only to avoid errors or inconsistencies in your implementation but also to conform to JavaScript and Tealium standards.

1. Str ing Values: Use string values for all non-product variables, including boolean and numeric data. Enclose all values in double-quotes and escape any double-quotes that might appear in the value itself (eg. utag_data.page_name = "On Sale: \"Red Hot\" Deals!";). For boolean values use “1” and “0” instead of true and false.

2. Amount Values: Use strings for all dollar amounts and exclude all currency symbols and commas eg. utag_data.order_total = "1234.00" instead of "$1,234.00".

3. Array Values: Use array values for all product related variables. The Tealium library, and each vendor tag integration, is designed to use arrays for all product-related data (price, quantity, ID, etc.).

4. No Extra Code: Do not add extra code to the UDO script block. If any code in the same script block fails then the UDO may not be defined correctly which will lead to unexpected execution of your vendor tags.


Page Types Tealium reserves a special variable in the UDO to identify the different types of pages (or templates) found throughout your site. All pages of your site should include a UDO variable named “page_type”. This is used to determine which type of page the user is viewing so that vendor tag functionality corresponding to those pages can be triggered. This variable will be used throughout Tealium iQ to configure Load Rules, Extensions, and Data Mappings. The suggested page_type values include, but are not limited to:

Page Type Value of page_type

Home Page home

Category / Product List category

Product Detail product

Search Results search

Account / Profile account

Cart / Basket cart

Checkout Flow (Billing, Shipping, Review) checkout

Order Confirmation / Thank You order

Generic generic Example Code The following is a sample UDO as it would appear on a page. This specific example shows properties that might appear on a "Shopping Cart" page with two products in the cart.

<script type="text/javascript"> var utag_data={ "country_code" : "US", "currency_code" : "USD", "page_name" : "Cart: View Shopping Bag", "page_type" : "cart", "product_id" : ["PROD123", "PROD456"], "product_name" : ["Red Shoes", "Black Socks"], "product_category" : ["Footwear", "Apparel"], "product_quantity" : ["1", "2"], "product_unit_price" : ["65.00", "4.75"], "cart_total_items" : "3", "cart_subtotal" : "74.00" }; </script>


The UDO can be updated with additional values outside of the declaration block, as long as the data gets set prior to loading utag.js. UDO variables set after loading utag.js will be ignored.

Page Specific Data When populating the UDO, only include variables pertinent to the current page type. This reduces clutter in the page code and eliminates confusion about what data is expected. Below is an example of a search page UDO that omits unnecessary items such as product and order data.

Product Arrays Product variables are to be populated as arrays, even when a single product is being set. Below are examples of setting the product ID variable with one product ID (eg. on a Product Detail page) and with three product IDs (eg. on a Shopping Cart page).

Array Alignment All product array variables should have the same number of elements to ensure data alignment. In this example, notice that the first element in each array corresponds to the first product. Properties associated with this product (such as ID, price, and quantity) all appear in the first element in each array, while the properties of the second product will appear in the second element in each array, and so on.

<script type="text/javascript"> utag_data["page_name"] = "View Cart"; </script>

<script type="text/javascript"> var utag_data={ "page_name" : "Search Results", "page_type" : "search", "search_results" : "42", "search_keyword" : "tennis shoes" }; </script>

// Single product (eg. product detail page) utag_data["product_id"] = ["PROD123"]; // Multiple products (eg. cart page) utag_data["product_id"] = ["PROD123", "PROD456", "PROD789"];

// Product 1 : ID=PROD123, Price=3.00, QTY=1 // Product 2 : ID=PROD456, Price=5.00, QTY=1 utag_data["product_id"] = ["PROD123", "PROD456"]; utag_data["product_price"] = ["3.00", "5.00"]; utag_data["product_quantity"] = ["1", "3"];


Tracking Functions The Universal Tag will automatically track standard page views, but there is often the need to track dynamic events. Dynamic events can include anything that occurs after the initial page load, such as link/button clicks, video interactions, or an AJAX content refresh.

The Universal Tag exposes two Javascript functions that allow a website to track these types of events: utag.view() and utag.link(). Each function takes one parameter--a Javascript data object (similar to utag_data).

utag.view()

Page View Tracking • Commonly used for AJAX page flows where the URL does not refresh as the user navigates the

site eg. accordion checkout or single-page application • The UDO declared on the initial page load (utag_data) is not re-purposed with these calls. You

must explicitly pass a new data object (or a modified utag_data) to this function • The Universal Tag automatically triggers this function on every page load Example:

Single Page Applications If your website loads utag.js only once per visit, and thus must manually trigger page views, you will suppress the automatic page tracking to allow for custom tracking of the page. The Universal Tag alllows you to override certain behaviors via a global object named "window.utag_cfg_ovrd". To override the automatic page tracking add this line to your page prior to loading utag.js:

utag.view({ "page_type" : "checkout", "page_name" : "Select Payment Option" });

window.utag_cfg_ovrd = {noview : true};


Once your application is loaded (and utag.js is loaded) you can add utag.view() tracking calls to your page code. These calls are typically triggered at the DOM-ready event or any event that causes a content view refresh.

utag.link()

Dynamic Event Tracking • Triggers a non-page view event • In some cases the jQuery OnHandler extension in Tealium iQ can be used to trigger this event

instead of coding this function into the page • Best practice is to use the variable "event_name" to control tag behavior

Tealium reserves another special variable in the UDO called "event_name" to uniquely identify each interaction that is tracked on the site. The value of this variable will be a plain-English descriptor of the event being tracked. This variable will be used throughout Tealium iQ to configure Load Rules, Extensions, and data mappings. Any additional data related to the event should be included in the UDO of the tracking call.

The suggested event_name values include, but are not limited to:

Event Value of event_name

Add to Shopping Cart cart_add

Remove from Shopping Cart cart_remove

Empty Shopping Cart cart_empty

View Shopping Cart (Modal) cart_view

User Registration Complete user_register

User Login user_login

User Logout user_logout

Custom Link/Button Click custom_click

Example:

utag.link({ "event_name" : "cart_add", "product_id" : ["PROD123"], "product_quantity" : ["2"], "product_unit_price" : ["12.99"] });


Triggering Specific Tags The default behavior of the "view" and "link" tracking calls is to trigger all vendor tags that support that specific event. However, there are cases when only one (or multiple) tag(s) should run for an event. The tracking calls can be extended with additional parameters to target only the tags that should fire. The key parameter is the UID of the tag from Tealium iQ, found in the far-right column of the "Tags" tag:

These UID's can be added as a third parameter to the utag.view and utag.link calls to target those tags.

Example:

Important: (1) Calling the tracking functions in this way will bypass the normal Load Rule logic and (2) the second parameter should always be null.

Event Tracking: Understanding Your Options The goal of event tracking is to collect information about your visitors’ interactions within a page. Whereas page view tracking gathers information about the navigation path a visitor takes, event tracking monitors what visitors do between navigation steps. And just as page view tracking requires a UDO to give context about what page is being tracked, event tracking also requires relevant UDO values be included in the tracking calls.

// "link" event, only fire tag UID 4, 3 and 9 utag.link(data_obj, null, [4, 3, 9]); // "view" event, only fire tag UID 4 utag.view(data_obj, null, [4]);


For example, the use of utag_data.page_type in the UDO helps distinguish different types of pages (product, search, cart, etc.) and the utag_data.event_name variable distinguishes the different events to be tracked (cart_add, newsletter_signup, user_login, etc.). Similarly, as certain UDO variables are only relevant to certain page types (eg. search_keyword on Search pages), only variables relevant to a tracked event are required in the tracking call (eg. customer_email when tracking newsletter signup).

More information about event tracking best practices.

The following options describe the various methods of integrating Tealium’s event tracking into your website.

Option #1 - jQuery Extensions Used for tracking basic interactions within a page, such as clicking, expanding, ticking, checking, selecting, etc. For site-wide custom click tracking a global markup strategy should be created to expose the necessary event attributes in the “data-” attributes of the elements to be tracked. The details of this approach would be included in the overall Data Layer recommendation.

Useful markup attributes include, but not limited to:

• data-event_name : the type of interaction with the element eg. click, form_start, change, etc.

• data-event_category : a general category for the type of action eg. navigation, forms,checkout, etc.

• data-event_label : a user friendly name of the element tracked

Note: Requires a web page with semantic markup.

Best Uses: link clicks, button clicks, form field interactions

Not recommended for: ajax page flows, form submissions

Option #2 - Coded utag.link, utag.view Used for tracking dynamic page content refreshes, ajax pages, modal form submissions or any event that requires a round-trip request/response to the client’s web server to fetch additional data not already present on the page.

https://community.tealiumiq.com/posts/915699-best-practices-and-implementation-review-guide

https://en.wikipedia.org/wiki/Semantic_HTML


Best Uses: modal forms, product quick view, single page websites, add to cart from non-product pages

Not recommended for: link tracking

Option #3 - Page UDO Used when an event occurs at the same time as a new page load. The default page view tracking can perform the event tracking at the same time provided the required UDO variables are present (eg. event_name). For example, in a cart checkout process, when asked to checkout as guest, new, or existing customer, if you select “existing customer” and login with correct credentials, the following page load might contain this UDO indicating it is the "Shipping" section of the checkout and that a "user_login" event has occurred:

Best Uses: user login, user registration, “success” pages

Not recommended for: modal forms, ajax pages

var utag_data = { page_type : "checkout", page_name : "Shipping Information", event_name : "user_login", customer_id : "0123456789" };


Option #4 - Video Video tracking often requires a custom Javascript code solution. This can be implemented within TiQ, but still requires coding to the specifications of the video platform’s API.

Event Tracking Options Summary There are many solutions possible for each scenario. Contact your account manager for further assistance.

Event Option #1 jQuery

Option #2 Coded

Option #3 Page UDO

Custom Link ✓

Cart Add ✓ ✓ ✓

Cart Remove ✓ ✓

Cart Empty ✓

User Login ✓ ✓

User Register ✓ ✓

Email Signup ✓ ✓

Prod QuickView ✓

Form Interaction ✓

Form Success ✓ ✓

Full Page Example Code The code below is a sample of how the Tealium UDO and Universal Tag might appear on a product detail page in a production environment:

<html> <head> <title>Product: Green Hawaiian Shirt</title> </head> <body> <script type="text/javascript"> var utag_data = { "page_type" : "product", "page_name" : "Product: Green Hawaiian Shirt", "product_id" : ["GRN_HI_SH_001"], "product_name" : ["Green Hawaiian Shirt"], "product_category" : ["Men's Shirts"], "product_subcategory" : ["Tropical"], "product_price" : ["55.00"] }; </script> <script type="text/javascript"> (function(a,b,c,d){ a='//tags.tiqcdn.com/utag/ACCOUNT/PROFILE/prod/utag.js'; b=document;c='script';d=b.createElement(c);d.src=a; d.type='text/java'+c;d.async=true; a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a); })(); </script>  </body> </html>


Appendix

A. Page Performance and utag.js Tealium employs the industry standard of loading our Javascript files asynchronously. This achieves two important goals of any third-party Javascript library: (1) it eliminates the risk that bad vendor code will break your web page and (2) it prioritizes the user experience (ie. page rendering) over tag tracking. By default the utag.js library also delays the firing of tags until the DOM-ready event, even further ensuring that it is not consuming precious browser processing time during the page load. Of course, most of this tag behavior is adjustable within Tealium iQ and can be customized for your website's specific goals.

The utag.js code can be placed anywhere within the <body>, although the top is the preferred location. The sooner the page can begin loading utag.js the sooner your tags will be ready to run when the page has been rendered.

There are valid scenarios to use synchronous code to load tags, such as A/B testing tools. If you require this functionality please contact your account manager about enabling this feature in your configuration.

B. Sample Data Layer The following table lists the variables of a sample data layer.

Sample Data Layer

Variable Description

page_type Type of page eg. home, category, product, search, cart, checkout, receipt, account

page_name Tealium variable to identify the page name

event_name Tealium variable to identify unique events eg. cart_add, user_login, email_signup, etc.

site_section The top-level sections of your site eg. Apparel, Accessories, Help, etc.

site_subsection1 The 1st level category of the page hierarchy

site_subsection2 The 2nd level category of the page hierarchy

site_subsection3 The 3rd level category of the page hierarchy

site_subsection4 The 4th level category of the page hierarchy

site_country_code The two-character country code of the site eg. us, uk, mx, ca, jp, etc.


site_language_code The two-character language code of the site eg. us, es, fr, etc.

search_keyword The search term entered by the user. eg. 'long sleeve'

search_results The number of search results eg. '42'

click_name During click tracking events, the name of the element clicked. eg. Submit, Login, etc.

click_category During click tracking events, the category of the element clicked. eg. Header, Navigation, etc.

order_id Unique Identifier for an order, should only be populated on Order Confirmation page.

order_total Total Amount of the Order including tax and shipping but less all discounts

order_subtotal The price of all items including any product or order level discounts, but excluding tax and shipping

order_discount_amount The order-level discount amount. eg. 10.00

order_payment_type The type of payment eg. visa, paypal

order_currency_code The three-character urrency code for the site eg. USD, GBP, EUR, CAD

order_promo_code A list of promotion codes applied to the order, comma delimited

order_shipping_amount The total shipping amount of the order

order_shipping_type The type of shipping used in the order eg. 'FedEx Priority'.

order_store Identifier of store type (i.e. web or mobile web)

order_tax_amount Total tax amount for this order

order_type An optional value to distinguish between types of orders eg. registry

customer_id The unique customer ID

customer_email The customer's email address

customer_city The customer's city of residence

customer_country The customer's country of residence

customer_first_name The first name of the customer

customer_last_name The last name of the customer

customer_state The customer's state/province of residence


customer_postal_code The customer's postal code

product_id An array of product IDs, the primary identifier for your products

product_sku An array of product skus

product_name An array of product names

product_price An array of product selling prices

product_quantity An array of quantities for each product

product_brand An array of product brands

product_category An array of product categories

product_subcategory An array of product sub-categories

product_discount_amount An array of product discount amounts, usually as a result of product-level coupons

product_original_price An array of original suggested retail product prices as strings with only digits and decimal

product_promo_code An array of promo/coupon codes applied to specific products eg. SHOES10OFF

product_image_url An array of URLs to the main product image

product_url An array of URLs to the individual product pages

cart_total_items Total number of all items in the cart.]

cart_total_value Total value for all items in the cart

cart_product_id On "Add to Cart" event, an array of all product ID's currently in the cart

cart_product_sku On "Add to Cart" event, an array of all product skus currently in the cart

cart_product_quantity On "Add to Cart" event, an array of all product quantities currently in the cart

cart_product_price On "Add to Cart" event, an array of all product prices currently in the cart


US Headquarters 11085 Torreyana Road Suite 200 San Diego, CA 92121 (858) 779-1344 tealium.com

Tealium has offices worldwide. Phone numbers and addresses are listed on the Tealium website at tealium.com/contact

http://tealium.com/

http://tealium.com/contact/

Tealium Technical Implementation Guide 4.39 - Magento...events: utag.view() and utag.link(). Each...

Documents

Transcript of Tealium Technical Implementation Guide 4.39 - Magento...events: utag.view() and utag.link(). Each...