JavaScript Code Extension

Prerequisites

• Permission to Manage JS Code Extension
  • This permission is required to add or edit a JavaScript Code extension in your account.
• utag version 4.38 or later. For more information about updating the utag.js template, see our knowledge base article Best Practices for Updating to the Latest Version of utag.js.
  • This version provides support for the execution options under the All Tags scope
  • Upgrade to this version if you have not already done so.

This is the basic version of the JavaScript Code extension. For advanced needs, see the Advanced JavaScript Code Extension.

JavaScript code extension comparison

The following table highlights the key differences between the JavaScript Code extension and the Advanced JavaScript Code extension to help you choose the one that best suits your needs.

How it works

The JavaScript Code extension gives you the power to create custom code to be included in the files that load on your site. Depending on the scope of the extension, the code loads in either utag.js or in a vendor utag.#.js file. The code entered into the text box of the extension is included in the utag files just as it appears. It is important to note that the code is run from an anonymous function wrapper, which ensures that the code is isolated and does not interfere with other scripts, as shown in the following example:

function(a, b) {
    // content of JavaScript Code extension runs here
}

The parameters represent the following:

• a: indicates which tracking call was made, where “view” corresponds to the utag.view() method for tracking page views, and “link” corresponds to the utag.link() method for tracking link clicks.
• b: a reference to the data object passed to the tracking call.

While the JavaScript Code extension is flexible and can be used for most anything you would want to accomplish within your tag management solution, it is important to understand the impact it could have on your account. We recommend that you try to use the other built-in extensions to accomplish your task before turning to the JavaScript Code extension.

Conditions

Conditions add an extra layer of control on top of the scope. These conditions control when the JavaScript Code extension runs.

Scope

The JavaScript Code extension offers the following options for determining the timing of when the code runs:

• utag Sync
• Pre Loader
• Before Load Rules
• After Load Rules (default)
• DOM Ready
• Tag Scoped
• After Tags

To learn about the order of operations in utag.js, see Order of Operations.

Occurrence

By default, a JavaScript Code extension runs for every tracking call, including in-page event tracking, which would potentially cause it to run more than once per page load. If you want to prevent multiple executions of your code, select Run Once.

You cannot change occurrence for extensions that use the following scopes:

• utag Sync
• Pre Loader
• DOM Ready
• Tag Scoped

Before You Begin

Consider the following before you begin:

• Do not surround the code with <script> tags since the content of the text box will be included in a JavaScript file exactly as you enter it.
• If you are referencing a variable from the utag_data object, such as page_name or language, use b['VARIABLE'].
  Learn more about the b object.
• If you are referencing a variable defined in the tag template of the scoped tag, such as account_id or base_url, use u['VARIABLE'].

Configuration Steps

Use the following steps to configure the JavaScript code extension:

1. Go to the Extensions Marketplace and add the JavaScript Code extension from the Advanced tab.
2. Title: Enter a name for this extension.
3. Scope: Choose from the following options:
   • utag Sync
   • Pre-Loader
   • Before Load Rules
   • After Load Rules (default)
   • DOM Ready
   • Tag Scoped
   • After Tags
4. Occurrence: Select when to run the extension:
   • Run Always: Run the extension for every tracking call on a page.
   • Run Once: Run the extension only once per page.
5. Enter your JavaScript code in the editor. The editor displays any errors and warnings.
6. Condition (optional)
   • Click Add Condition and create a conditional statement.
   • The first drop-down list is populated with variables and the second drop-down list provides a list of evaluating operators.
   • If you are running the conditional logic against a value, enter it in the text field.
   • To apply multiple conditions, choose between the AND and OR logic.
7. Save and publish the changes.

Troubleshooting

Why can’t I edit the code in the editor?

You do not have the Manage JS Code Extension permission in your Tealium iQ account. Contact your Tealium account administrator to obtain the permission.

Why can’t I set the scope to Pre Loader?

If you have a condition defined, the Pre Loader option is no longer available. In Pre Loader scope, the data layer is not yet populated so there is no data object with which to evaluate the conditional logic. Likewise, the Add Condition option is disabled when the scope is set to Pre Loader.

What’s the difference between an extension run in the Pre Loader scope and one run in Before Load Rules scope with occurrence set to Run Once?

In both cases, the extension to runs once before load rules are evaluated. The differences between the scopes are:

• The Pre Loader scope does not support conditions.
• Extensions in the Pre Loader scope execute before the data layer is processed and cannot access the data layer b object (it doesn’t exist yet).
• The code in an extension scoped to Pre Loader is not wrapped in the anonymizing function and is executed exactly as it appears in the editor. For more information, see Code Execution.