iQ Tag Management

The JavaScript Code Extension gives you the power to write code to be included in the files that load on your site and is designed for implementing custom JavaScript code through Tealium iQ. This extension includes a rich code editor, the ability to create and save one or more drafts, and an advanced publish workflow to safely release your changes.

In this article:

Table of Contents Placeholder

Prerequisites

The following is required to use this feature:

utag v4.38 or higher (Learn more about upgrading to the latest version of utag.js).
To create drafts of code you must have the Manage JavaScript Code Extensions account-level permission.
To publish this extension you must have the JavaScript Draft Promotion profile-level permission.

How It Works

The JavaScript Code extension has its own publish workflow that uses drafts and a publish queue. Drafts are in-progress versions of the code that are preserved when you save the profile, but are not included in the published files by default. The publish queue allows you to mark a draft to be published, which causes it to become read-only and includes it in the next publish to the corresponding environment.

This new publish workflow ensures that your code doesn't get published until it's ready. It allows you to see what code has been published to each environment and easily compare code between drafts and environments.

For information about using the JavaScript Code extension with GitHub, see Syncing with GitHub

Drafts

Drafts are named versions of the JavaScript code. Each instance of the extension can have up to 20 drafts. Drafts are are saved each time the profile is saved, but are only published when they are explicitly added to the publish queue for specific environments. This allows you to edit code and save your progress (even if it is incomplete), without affecting your publish environments.

Publish Workflow

The JavaScript Code extension has its own publish workflow to provide safer and more granular control over what code gets published. Drafts are not published by default. To publish a draft, you add it to the publish queue for it to be included in the next publish.

You must have the JavaScript Draft Promotion permission to add a draft to the publish queue.

Here's how it works:

Create a Draft
Add a new draft and write your custom JavaScript code. Save (or publish) the profile and the code in the draft will be saved but not published. Continue working on your code in this way until it's ready to be published.
Queue for Publish
When you are ready to publish the code in a draft, add the draft to the publish queue for one or more publish environments. The draft enters read-only mode (indicated by the padlock icon) until the next publish to the selected environments, at which point it will become editable again, except in libraries. The color of the padlock next the draft will match the icon next to the corresponding environment.
Published Environments
Once a draft has been published, the live code can be reviewed (read-only mode) in the corresponding publish environments. You cannot edit the code in a publish environment directly. To make changes, edit a draft and repeat the publish workflow process.

Code Editor

The JavaScript Code extension employs an advanced code editor (Ace Editor) built into the interface that offers the following convenience features:

Syntax Checking
See syntax errors, warnings, and tips as you type. The margin displays helpful icons to indicate that your attention is needed on the affected line.
Syntax Highlighting
Language aware syntax highlighting for JavaScript.
Auto Indent/Outdent
Automatic indenting as you type. Supports the tab key and shift+tab key bindings.
Code Folding
Collapse blocks of code so you can eliminate distractions and focus on your changes.
Full Screen Mode
Expand the code editor window to full screen mode to work on larger code projects.

Code Execution

Once a draft is published, the code is added to one of the utag files (depending on the scope). It's important to note that the code runs just as it appears in the code editor, but is wrapped in the following anonymous function:

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

The two parameters passed to the function are:

a - the event type ("view" or "link" or a custom value)

b - a reference to utag_data allowing you to set UDO values as b.VARIABLE_NAME="somevalue".

Be sure to scope all of your variable references accordingly to avoid overwriting global variables.

Compare Code

You can compare a draft or a publish environment to any other draft or publish environment. The comparison window displays the versions of the code side by side with highlights for each line that differs. For example, you could compare Prod vs QA, Draft 1 vs Draft 2, or Draft 1 vs Prod.

Using the Extension

Before you begin, familiarize yourself with how extensions work.

Working with Drafts

Add code to the extension using drafts. To create a draft and enter JavaScript code:

In the sidebar, under Drafts, click + Add.
In the text window, type or paste your JavaScript code.
Save the profile to preserve your changes.

The following functions are available when working with a draft:

Draft Name
Set the name of the draft. The name will appear in the sidebar, sorted alphabetically in the list of drafts.
Reset
Undo all code edits made to a draft since the last time the profile was saved.
Delete
Delete the draft. This can be undone if you refresh the profile without saving.
Compare Diff...
Compare the draft with another draft or with a publish environment.
Queue for publish...
Mark the draft to be published in one or more publish environments.

Copy the File to Draft Mode

Files added through GitHub are read only and cannot be edited. To edit these files, edit directly in GitHub or copy the file to Draft mode and edit the draft copy.

Use the following steps to copy the file to draft mode, edit, and save prior to publishing:

Select the file you want to copy to Draft mode.
Click Copy to Draft to copy the content of the file into a new draft template.
Enter a name and press Enter.
You can enter a new name or keep the same name.

If you choose to keep the same name, names will remain the same as the file name. For example, if the GitHub filename is Tealium.js, the first copy will be Tealium.js (if a draft with that name does not already exist). Subsequent copies are named Tealium.js-1, Tealium.js-2, and so on.
Open and edit the copy.
Click Save.

Publish a Draft

Publishing a draft is a two-step process. First, in the extension the draft must be added to the publish queue for the desired publish environment. Second, the profile must be published to the corresponding target.

Remember, by default, drafts are not included in a publish unless they have been explicitly queued for publish.

To publish a draft:

Select the desired draft in the sidebar.
Click Queue for publish....
Check the box next to the desired publish locations.
Click Continue.
The draft will now be in read-only mode (indicated by the padlock icon) and the queued publish environment will be indicated in the sidebar and in the draft details.
Perform a Save/Publish on the profile, selecting the publish target matching the publish queue.
The published draft now displays as the active code in the corresponding publish environment in the sidebar.

Working with GitHub

The following sections describe how to synchronize GitHub files in TiQ.

When working with GitHub files in TiQ, the filename you are working with always displays at the top of the interface. To view the full file path, simply hover over the filename.

Add a GitHub File to TiQ

Use the following steps to add a file from GitHub to TiQ:

In the left panel of the JavaScript Code Extensions screen, next to GitHub Files, click + Add.
You will be prompted to enter the URL for the file you want to add.
Enter the URL.
Example: https://github.com/your_account/your_repository/blob/master/Tealium.js
Click Add File.
The code is now available to the extension.

Synchronize the File

You can automatically sync files by opening the JavaScript Code Extension. All GitHub files attempt to sync when you open the extension unless the file is approved for publish.

Use the following steps to manually sync files, including those approved for publish:

Select the file to sync.
Click Sync File to retrieve the latest copy of the file
The update file displays with the time and date and a green check mark to indicate that the file is up-to-date.

Queue the File for Publish

Files queued for publish cannot be synced and display a lock icon to the right of the filename. If you attempt to sync a file that is queued to publish, an orange warning icon displays to indicate that the you are unable to connect to sync to new version.

Use the following steps to queue your file for publish, as you do when using the JavaScript Draft Extension

Select the file to queue for publish.
Click Queue for Publish.
The file status displays a new line with the timestamp and username showing the environments the file will publish to.

Best Practices

Tips

Use the following tips to make the best use of this extension and avoid common mistakes:

Omit <script> Tags
Do not surround the code with <script> tags. The content of the text box will be included in a JavaScript file exactly as you enter it.
Reference the UDO
If you are referencing a variable from the utag_data object, such as page_name , use the b object like this: b['page_name']. Learn more about the b object.
Reference Tag Template Variables
If you are referencing a variable defined in the tag template of the scoped tag, such as account_id , use u['account_id'].
Create Useful Draft Names
Your iQ profile is a shared working environment so use meaningful names for drafts to make them easily identifiable to you and others.
Comment Your Code
Write useful comments to make it easier for your future self and other users to understand your code and how to maintain it.

Understanding the Pros and Cons

While the JavaScript Code extension is very flexible and can be used for virtually anything you would want to accomplish within your tag management solution, it's important to understand the impact it could have on the long-term success of your account. We strongly recommend that you try to use the other built-in extensions to accomplish a task before resorting to the JavaScript Code extension.

Consider your environment and the following pros and cons prior to using this extension:

Pros
Fully customizable code can accomplish virtually anything that can be done in JavaScript. Faster for developers that are more familiar 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 are not updated if you change the name of a variable in the data layer (i.e. if you change the name of a variable you must also change all occurrences of that variable within JavaScript Code extensions.)

FAQ

Can I continue using the deprecated JavaScript Code extension?

Yes. The older versions of the JavaScript Code extension will continue to operate normally, but you will not be able to add a new one using the old version.

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

The following reasons may explain why you are unable to edit the JavaScript Code extension:

You many not be able to add or edit the JavaScript Code Extension if you do not have the Manage JS Code Extension permission in your Tealium iQ account. Contact your account administrator to obtain this permission.
A draft will be in read-only mode if it has been queued for publish and the publish has yet to occur. You can remove the draft from the publish queue or publish the profile to make the draft editable again.
The code displayed in publish environments cannot be edited directly. This is a read-only view of the published code.

Why can't I select a publish environment in the Queue for Publish dialog?

While you might have permission to add the JavaScript Code extension and create drafts, there is a separate permission needed to promote a draft to a publish environment. If you do not have this permission, the environments in the Queue for Publish dialog will not be selectable.

Check with your account administrator to see if you have the JavaScript Draft Promotion permission.

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

If you have a condition defined, the Pre Loader option will not be 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 Pre Loader and Run Once before Load Rules?

Both Pre Loader and Run Once Before Load Rules will cause the extension to run once before the data layer is populated and before load rules are evaluated. The difference is that conditions are not supported in the Pre Loader scope.