A guide to Tealium's best practices for implementing Tealium iQ

The purpose of this document is to outline certain best practices that can help achieve the best possible implementation of Tealium iQ.

In this article:

Table of Contents Placeholder


Grouping Extensions

Group extensions by their scope, in the following order:

  • Pre Loader
  • All Tags
  • Tag Specific
  • DOM Ready

Learn More: Order of Operations

Pros Cons

Easier to navigate extensions

Extra effort to re-order extensions

Cleaner profile


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: 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.


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 (utag.js) 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

"event_name" Value

Cart/Basket Add


Cart/Basket Remove


Cart/Basket Empty


Cart/Basket View


Registration Event


Login Event


Logout Event


Link Clicked


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_")


jQuery Extension vs.

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.

Learn More: Asynchronous vs. Synchronous

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.


Bundling 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.


Wait Flag

The Wait Flag determines whether tags get executed immediately or at DOM Ready. When the Wait Flag is "No", tags are executed as soon as they are loaded into the page. When the Wait Flag is set to "Yes", tags wait 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.