Best Practices for Tealium iQ

A guide to best practices for implementing Tealium iQ.


Save vs. Save As

There are two methods to save your changes:

  • Save – Saves the changes within the current version, overwriting the previous revision.
  • Save As – Saves the changes in a new version, preserving the previous version.

Scenarios to use Save As:

  • When the current version has been published to production, to preserve the option to revert back, use Save As.
  • When beginning a new project, use Save As to create a new version to separate it from the previous work.
  • When you unsure which option to choose, the Save As method is safest because it allows you to revert to the previous version.

Learn more about saving and publishing.

Example: Save vs Save As to preserve the Prod version

In this example, there is a version published to Prod and we want to preserve that version that we can revert back it if necessary.


“Version A” is published to all three environments (Dev, QA, and Prod). After making changes, a Save As is performed to create a new version, “Version B”. It is then published to all environments again. This provides the option to rollback to the previous Prod version (Version A) if necessary.


“Version A” is published to Prod multiple times using a Save. There is no way to rollback to the previous Prod version if needed.

Pros Cons
The ability to revert to previous version. None
Better organization on the Versions screen.

Labels and titles

Use labels to categorize related tags, load rules, and extensions, especially those that require a sequential order.

Use descriptive titles, such as Step 1 of 3.

Pros Cons
Helps maintain the order of operations for extensions. Minimal effort to assign labels.
Ability to filter on labels to easily find tags and extensions.

Data layer object

This content has been moved: Data layer best practices

Event tracking

Replace hard-coded vendor tags

When adding event tracking code to your site, we recommend replacing all existing hard-coded vendor tags with Universal Tag tracking code. The behavior of individual tags can be controlled within the iQ console.

Pros Cons
Centralizes the management of event tracking to the iQ console. Developers might be more familiar with the vendor’s code.
Once you learn to do event tracking within Tealium, you will not have to learn vendor-specific event tracking solutions.
You can reuse event names and variables for multiple vendors, which eliminates duplicate work.

Event names

Tealium uses the variable tealium_event to uniquely identify each event type that is tracked on the site. Set this variable to a value identifying the event being tracked (Tealium naming convention applies).

Suggested values include, but are not limited to:

Event Type tealium_event
Cart/Basket Add cart_add
Cart/Basket Remove cart_remove
Cart/Basket Empty cart_empty
Cart/Basket View cart_view
Registration Event user_register
Login Event user_login
Logout Event user_logout
Link Clicked link_click

Sample event tracking script{
    tealium_event    : "cart_add",
    product_id       : ["shrt123"],
    product_price    : ["12.50"],
    product_quantity : ["2"]
Pros Cons
Implementation is clearer due to consistent variable names and values. An additional variable to implement in all event tracking calls.
Data mapping is easier because there is a single identifier for event types.
Event are grouped into categories by the prefix of the name (product_, cart_, user_)

Tealium has two options for tracking clicks and other events on a site:

  • Configuring the jQuery extension in the iQ console.
  • Coding directly in the page.

The jQuery extension is recommended for tracking click activity. If there are many links to be tracked, developing a strategy that simplifies this method creates a more maintainable implementation.

Learn More: Event Tracking - JavaScript (Web)


Load utag.js asynchronously

The best practice is to loading all tags and vendor code asynchronously. In this method, tags are loaded in parallel to the rest of the page content. This means that even if the tag is slow to respond or to load, it will not slow down the rest of the site.

Pros Cons
Asynchronously loaded files will not affect page load speeds. Less control over the timing of loading file. Mainly affects A/B testing vendors.
External files that are slow to respond will not halt page load or break the page.

Bundle tags

The Bundle Tags feature is set within the publish settings of the profile. Enabling this feature will cause the vendor tag code to be included in the main utag.js file. This reduces the number of HTTP requests that are sent from your page and improves performance.

Learn More: Tags: Advanced Settings (Bundle Flag)

Pros Cons
Reduces the overall size of Tealium files that load on your site due to more efficient gzip compression. Added risk that a published syntax error in a bundled tag will cause the utag.js file to fail.
Important tags (analytics) execute sooner which improves tracking on landing pages.
Fewer network requests from the page since more tags are placed within utag.js instead of their own utag.#.js files.

Page code placement

We recommend that the Universal Tag (utag.js) be placed at the top of the body tag (as opposed to the head or footer), keeping in mind that the data layer object must be declared and populated prior to this. This placement provides the best compatibility with the greatest number of vendors.

Pros Cons
More control over when tags fire (early in the page or later). Could require extra development to ensure the data layer object is available before utag.js is loaded.
Better compatibility with multivariate testing tags.

Tag timing

The Tag Timing setting determines if a tag is fired immediately or at DOM Ready. When Tag Timing is set to Prioritized, the tag is executed as soon as it’s loaded into the page. When Tag Timing is set to DOM Ready, the tag waits until the DOM Ready event to execute. This setting is found in the Advanced Settings for each tag.

To prioritize the execution of important tags (such as analytics), set the Wait Flag to off.

Pros Cons
Important tags can be prioritized to execute as soon as possible to maximize data collection. The browser could prioritize loading a tag over loading an image to display which may have a slight impact on user experience
On landing pages, where tag files most likely have not been cached, the tags will execute sooner.


Use built-in extensions

Tealium is designed for both non-technical users with limited coding experience and for developers who are comfortable writing their own JavaScript. While many of the built-in extensions could easily be re-written as custom JavaScript Code extensions, we recommend using the built-in extensions whenever possible and only writing custom JavaScript when you require additional functionality not offered by the existing options.

Built-in extensions offer the following benefits:

  • Managed Dependencies
    If the name of a data layer variable is changed, all built-in extensions that reference that variable are automatically updated because they contain a reference to the original variable.
    Data layer variables referenced in code, such as b['user_login_status'], must be updated manually if the name of the variable ever changes.
  • Friendly Variable Names
    Built-in extensions will always display the user-friendly name of a variable (Alias) if it exists. This improves readability of the configuration.
    Variables referenced in code must use the actual name, which can be cryptic or unclear, making it more difficult to understand what the code does or to identify its dependencies.
  • No Syntax Errors
    Built-in extensions are guaranteed to generate the same consistent code every time you publish, eliminating the risk of syntax errors.
    Custom JavaScript code always runs the risk of introducing unexpected syntax errors (although the publish engine will usually catch these) or runtime errors.
Pros Cons
Easier to understand and maintain for most users. May take slightly longer to set up.
Easier to debug when an issue arises.
Built-in extensions are safe and will not introduce JavaScript errors.

Global vs. local JavaScript variables

In JavaScript Code extensions, be sure to explicitly define global and local variables using var and window. This prevents naming conflicts with the variables declared in utag.js or globally in the page.


variable_name = "some value";


var variable_name = "local value";
window.variable_name = "global value";
Pros Cons
Avoids collisions with other variables elsewhere on the site.

Was this page helpful?

This page was last updated: January 7, 2023