This article covers the fundamentals of the utag.sync.js script and describes how to enable and install it on your website.

In this article:

Table of Contents Placeholder


To complete the steps described in this article, you must have the following Tealium iQ Tag Managment profile-level permissions (Learn more):

  • Manage Tag Template
    This permission is required to add and manage tag templates.
  • JavaScript Draft Promotion (Optional)
    This permission is required to publish JavaScript extensions.

How it Works

Before You begin, it is important to learn the differences between synchronous (sync) and asynchronous (async) JavaScript and how it relates to your iQ Tag Management (TiQ) installation. (Learn more).

The utag.sync.js script described in this article is an additional file that you can add to your pages to support A/B and multivariate testing tags, such as Adobe Target or Optimizely. The script is placed in the <head> section of your page code and loads synchronously to comply with the most common vendor requirements. The file content is managed within TiQ.

Enabling utag.sync.js

By default, the utag.sync.js file is not published to the Content Delivery Network (CDN) when you save and publish your TiQ account/profile. It must first be enabled. Upon the next save and publish after enabling, the file is available. This setting is applied at the profile level.

Use the following steps to enable the utag.sync.js script:

  1. Log in to your TiQ account/profile.
  2. Click Save/Publish in the upper right corner.
    The Save/Publish dialog displays.
  3. Click Configure Publish Settings in the upper right.
  4. From the General Publishing tab, scroll down to the Implementation section and use the slider to set Generate utag.sync.js File to On.
  5. Click Save.
  6. Save and publish your profile.
  7. Click Client-Side Versions in the lower left of the sidebar to ensure that utag.sync.js displays as a link in the revision notes on the Versions screen.
    WhiteUI_TiQ_Using the utag_sync_js Script_View file.jpg
  8. Click the View utag.sync.js link to view the contents of the file from the published location on the CDN.

Adding utag.sync.js to Your Site

According to most vendor requirements, the utag.sync.js script is designed to be placed in the <head> section of a page. The script should be placed in the same location that your vendor code would typically load to ensures that the vendor code loads prior to the content of the page, which provides an optimal user experience as the page renders.


<script src="[account]/[profile]/[env]/utag.sync.js"></script>

The path to the utag.sync.js file contains the following parameters:

  • account – the name of your TiQ account.
  • profile – the name of the profile within your TiQ account. The default value is main.
  • environment (env) – one or more publish environments: Dev, QA, Prod, or Custom.

You can retrieve your specific script from the Code Center of your account, as follows:

  1. Click Save/Publish in the upper right corner.
    The Save/Publish dialog displays.
  2. Click Code Center in the upper right corner.
    The Tealium Script tab displays code that you can use to cut and paste into your file.
    TiQ_Code Center_Prepend utag.js path with https_Highlighted.jpg
  3. Click the Sample HTML tab to view sample HTML for the utag.sync.js placement.
  4. Cut and paste the sample HTML for use on your page as needed.
  5. Click OK and then click Cancel to close the window.

Adding Vendor Code to utag.sync.js

The content of the utag.sync.js file is managed directly from the Manage Templates menu. In this step, you will paste the code provided by your vendor into the utag.sync.js template. The code used should only contain JavaScript code and must not contain any HTML tags, including the <script> tag.

Use the following steps to add the code to the utag.sync.js template:

  1. Check to ensure that you have the Manage Tag Template permission, as listed as a prerequisite at the beginning of this article. (Learn more)
  2. Click your user icon on the top right and select Manage Templates from the drop-down list.
  3. From the template drop-down list, select uTag Sync (Profile) UID: sync.
    WhiteUI_TiQ_Using utag_sync_js_Manage Templates_Select Template.jpg
    The template configuration file displays and is ready to edit.
  4. Paste your code below line 3. Do not alter lines 1 and 2.
    WhiteUI_TIQ_Using utag_sync_js_Edit and Save Profile Template.jpg
  5. Click Save Profile Template.
  6. Save and publish your changes to the Dev or QA environments to validate before publishing to Prod.

    Loading a script synchronously in the <head> forces the page to wait for that code to run before it can parse and render the remainder of the page content. Errors encountered in the code for this script could potentially prevent the page from loading. For this reason, it is strongly recommended to always publish utag.sync.js to Dev or QA for testing before publishing to Prod

    The utag.sync.js script is now successfully implemented in your profile.
  7. Once validated, you can repeat the save and publish steps to publish to your production environment.

Special Considerations

Accessing the Universal Data Object (UDO)

The utag.sync.js file will likely load before the Universal Data Object (utag_data), therefore the code may not be able to reference those variables. Ensure that you thoroughly test any custom code that you intend to use when editing utag.sync.js file.

Publishing to Production

Once utag.sync.js is enabled in the profile, all subsequent publishes to the Prod environment include this file. While it cannot be excluded from the publish to Prod, the code within it can be customized with logic to control the behavior in the production environment. To control what code will run in each environment, wrap your vendor code in an if-else statement that uses a condition to distinguish between the QA and Prod environments.


The following example uses an if and else statement for code that runs based on the JavaScript variable document.domain:

if(document.domain === '') {
    // Run code for the live production site
else {
// Run code for the non-production site