Websites

Installation Instructions for TagCommander on Websites.

It is necessary to implement one or multiple Container and optionally a Data Layer and event Trigger to install TagCommander on a website.

Websites use the Client-Side version of TagCommander.

Container Setup

A TagCommander Container is a version-controlled JavaScript file that bootstraps the tag management system functionality on a website. To implement and update Tags, users will generate new versions of the Container JavaScript file.

Definitions

Metric

Description

Container ID

Unique ID of the Container within your account. e.g. 21

Container Name

Label for the Container. Can be configured in the Options of TagCommander. e.g. "Header Container"

Container Filename

Name of the Container JavaScript file, can be configured in the Options of the TagCommander interface. e.g. "tc_header_21.js"

Container URL

Complete URL of the Container used for installation. Depends on the hosting method. e.g. "//cdn.tagcommander.com/1234/tc_footer_main_20.js"

Container Version

Snapshot of a Container JavaScript file.

Installation

To implement TagCommander it is necessary to implement one or multiple TagCommander JavaScript Container files on the website. The URL of each JavaScript Container file will be provided alongside the Container IDs and Container Names by a Commanders Act Consultant during the setup process. Here you can find an overview of common Container setups.

Container are usually installed by implementing a <script> html node on every page of your website that holds a src attribute that points to the Container URL. TagCommander differentiates two types of Container to define whether the Container should be placed in the <head> or in the <body> section of the HTML document.

Installation of `<head>` Container

<head> Container are used to implement A/B-testing and personalisation Tags that usually impact the visual content of a website before it is presented to the user. Therefore it is important to place them as high as possible in the <head> section of your website.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="{{ head_container_URL }}"></script>
        (...)
    </head>
    (...)
</html>

Please ensure that the <head> Container file is loaded synchronously to avoid potential content flickering effects.

Installation of `<body>` Container

<body> Container are used to implement Tags that measure information. These Containers are therefore placed at the end of the <body> section to make sure they have minimal impact on the loading time of the content of the website.

<!DOCTYPE html>
<html>
    (...)
    <body>
        (...)
        <script src="{{ body_container_URL }}"></script>
    </body>
</html>

In contrast to the <head> Container it is possible to implement <body> Container asynchronously. For example it is possible to load them via JavaScript on the onload event of the page or it is possible to use the async attribute in the <script> element.

Installation via JavaScript Loaders

It is possible to implement JavaScript Container files with JavaScript loaders like RequireJS or HeadJS. On the opposite it is not possible to bundle the JavaScript Container files with bundlers like Webpack or ParcelJS to make sure that the Container files are dynamically loaded from the CDN or server on each page request. Otherwise users will not be able to manage TagCommander Container on their own.

Testing

Via JavaScript Console

It is possible to log all loaded Container files on a site via the JavaScript console of the browser. The JavaScript object tC.containersLaunched provides information of each loaded TagCommander Container.

Following you will find an example object including its most relevant information:

{
    1234: { // TagCommander Account ID
        1: { // ID of the 1st loaded Container
            g: 15,
            v: "5.15" // Version of the 1st loaded Container
        },
        5: { // ID of the 2nd loaded Container
            g: 20,
            v: "55.16" // Version of the 2nd loaded Container
        }
}

Via Chrome Extension

The Commanders Act Assistant Chrome Extensions shows all loaded Container files on a page including their version and other information.

Data Layer Setup

A TagCommander Data Layer is a JavaScript object that holds metadata of a website as properties to make it available to Tags. In TagCommander this Data Layer is named "External Variables" to distinguish it from scripted "Internal Variables" that are generated within the Container JavaScript.

Installation

To install a TagCommander Data Layer it is necessary to implement a global JavaScript object tc_vars that holds the meta data of the page as direct properties. The required Data Layer properties are defined during the TagCommander setup process, but you can find a list of common properties here.

Re-using an Existing Data Layer

In case a website already has a Data Layer installed it is possible to transform it into a TagCommander Data Layer. Please contact a Commanders Act consultant to implement the transformation.

The approach to fill the Data Layer with properties depends on the technology framework that is used on the website and can reach from JavaScript web scraping to templating to hardcoding.

<script>
    window.tc_vars = {
        env_template: "homepage",
        env_work: "prod",
        page_name: "Homepage",
        page_keywords: ["homepage", "home", "entrypage", "index"],
        product_name: "",
        (…)
    };

    window.tc_vars.user_name = "myuser";
</script>
<script src="{{ container_URL }}"></script>

The Data Layer needs to be filled with information before the TagCommander Container file is loaded—otherwise information might not be available at the time the Container JavaScript executes.

Race Conditions

Race conditions between the Data Layer properties and the Container JavaScript can be difficult to identify and debug by TagCommander users. It is therefore important to avoid them during installation!

In case multiple Containers are used on the same page it is possible to fill the Data Layer in multiple steps. Global information like the page type should be made available before the first Container is loaded. Information that is only relevant for a certain Container (e.g. product information) can be appended prior to the respective Container.

Following example outlines how a Data Layer can be installed in case both a <head> and a <body> Container are used on a website.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <script>
            window.tc_vars = Object.assign({}, window.tc_vars, {
                env_template: "homepage",
                env_work: "prod"
            });
        </script>
        <script src="{{ head_container_URL }}"></script>
        (…)
    <head>
    <body>
        (…)
        <script>
            window.tc_vars = Object.assign({}, window.tc_vars, {
                page_name: "Homepage",
                page_keywords: ["homepage", "home", "entrypage", "index"]
            });
        </script>
        <script src="{{ body_container_URL }}"></script>
    </body>
</html>

Data Layer Naming Convention

As outlined in the example above the properties of the Data Layer are usually grouped with a prefix notation. E.g. env_ is used to group environment information and user_ is used to group user information.

In case a property is not relevant for a certain page (e.g. product_name on the privacy policy page) it is recommended to fill it with an empty value (e.g. "", 0, [] or {}).

Testing

Via JavaScript Console

It is possible to investigate the Data Layer in the JavaScript console by logging tc_vars.

Following you will find an example output of a tc_vars Data Layer in the JavaScript Console.

{
    env_template: "homepage",
    env_work: "prod",
    page_name: "Homepage",
    page_keywords: ["homepage", "home", "entrypage", "index"],
    product_name: "",
    (…)
}

Via Quality Assurance Tag

The Tag template Commanders Act - Data Layer QA in the TagCommander Tag library automatically outputs Data Layer information to the JavaScript console on each page. This approach has the advantage that it logs a snapshot of the Data Layer at the exact time the Container JavaScript was executed. This allows to identify race conditions between the Data Layer properties and the Container JavaScript to make sure all necessary properties are available in time.

Via Chrome Extension

The Commanders Act Assistant Chrome Extensions shows the Data Layer properties of the currently visited page.

Trigger Setup

TagCommander Triggers are onsite events that are used by TagCommander users to dynamically execute Tags.

Definitions

Metric

Description

Trigger Label

Label for an event that is used by TagCommander users to execute Tags. e.g. add_to_basket

Trigger Data Layer

A JavaScript object that can be accessed by Tags that are executed on the related Trigger. e.g. product_id

Installation

TagCommander allows to set up common Trigger automatically without the involvement of technical personnel (e.g. Container loaded, DOM ready or Vertical Scroll 25%). In cases where the default Triggers are not sufficient it is possible for technical personnel to implement custom Triggers. The necessary Trigger are defined during the TagCommander setup process, but you can find a list of common Trigger here.

To install a custom Trigger on the website it is necessary to call a JavaScript function with the following pattern:

tC.event.{{ Trigger Label }}(this, {{ Trigger Data Layer }});

A typical example is an Add to basket event where the product id of the selected product is sent with the event:

tC.event.add_to_basket(this, { product_id: "12345" });

Trigger Data Layer Properties

A common approach for the Trigger Data Layer is to always use the same properties like event_label, event_type and event_value—so in case of an add_to_basket Trigger the event_value would hold the product id of the selected product and in case of a video_play event the event_value would hold the current position within the video timeline. This allows to avoid to create multiple custom variable names for each individual event and therefore makes Trigger more generic.

Trigger Error Handling

In some situations it might happen, that a user interacts with a custom Trigger before the TagCommander JavaScript Container file was loaded. In this case using the Trigger function would cause a JavaScript ReferenceError. Therefore it is recommended to check the availability of the Trigger function before using it.

if (tC && tC.event && typeof tC.event.add_to_basket === "function") {
    tC.event.add_to_basket(this, { product_id: "12345" });
}

Testing

Via Quality Assurance Tag

The Tag template Commanders Act - Data Layer QA in the TagCommander Tag library automatically outputs Data Layer information to the JavaScript console when executed. Assigning this Tag with the Trigger allows to log a snapshot of the Data Layer when the respective Trigger is executed.

PreviousVueJS NextGetting Started

Last updated 4 years ago

Container Setup

Definitions

Installation

Installation of <head> Container

Installation of <body> Container

Installation via JavaScript Loaders

Testing

Via JavaScript Console

Via Chrome Extension

Data Layer Setup

Installation

Re-using an Existing Data Layer

Race Conditions

Data Layer Naming Convention

Testing

Via JavaScript Console

Via Quality Assurance Tag

Via Chrome Extension

Trigger Setup

Definitions

Installation

Trigger Data Layer Properties

Trigger Error Handling

Testing

Via Quality Assurance Tag

Installation of `<head>` Container

Installation of `<body>` Container