JavaScript Code (Basic) Extension

This is the basic version of the JavaScript Code extension. For advanced needs, see the Advanced 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.

How it works

The JavaScript Code extension give 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, but it is important to note that the code is run from an anonymous function wrapper, 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 “view” for utag.view() and “link” for utag.link().
• 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.

Consider the following Pros and Cons of using the JavaScript Code extension:

Pros

• Fully customizable code can accomplish most anything that can be accomplished using JavaScript.
• Faster and more familiar for developers that are accustomed to writing front-end JavaScript.

Cons

• Difficult for non-developers to understand and edit.
• More difficult to maintain over time.
• Prone to typos and logic errors.
• Variable names are hard-coded and therefore not updated if you change the name of a variable on the Data Layer tab.
• A changed variable name will not be propagated to the JavaScript Code extension. For example, if you change the name of a variable you must also change all occurrences of that variable within JavaScript Code extensions.

Conditions

Conditions add an extra layer of control on top of the scope. You can apply any number of conditional statements in the Set Data Values and Join Data Values extensions. These conditions control when the JavaScript Code extension will run.

Execution order and run once

The JavaScript Code extension offers the following options for determining the timing of when the code will run. To learn about the order of operations in utag.js, see Order of Operations.

• utag Sync
• Before Load Rules
• After Load Rules (default)
• After Tags
• Run Once after Load Rules
• Run Once before Load Rules
• Run Once after Tags

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, choose one of the Run Once options in the execution drop-down list. These options are only available in the All Tags scope and require utag v4.38 or later.

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:
   • Preloader (does not support Conditions)
   • DOM Ready
   • All Tags
   • Vendor Tag(s)
4. Execution: This drop-down list is only available to the All Tags scope. Choose one of the following options:
   • Before Load Rules
   • After Load Rules (default)
   • After Tags
   • Run Once after Load Rules
   • Run Once before Load Rules
   • Run Once after Tags
5. Enter your JavaScript code in the editor. The editor will display 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.

FAQ

Why am I unable to add or edit the new JavaScript Code Extension?

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 select Preloader with Conditions?

In the preloader state, the Data Layer is not yet populated and there is no utag data with which to evaluate the conditional logic. For this reason, the Conditions drop-down selections are greyed out when Preloader is selected.

What’s the difference between Preloader and Run Once Before Load Rules?

Both will cause the extension to run once before the Data Layer is populated, except the Preloader does not support conditions. Be mindful of this caveat when configuring the scope.