1 of 11

Setup guides for developers

In this section you will find all our guides for implementation of a browser side tracking trough a web container

Web container setup

A web container is a JavaScript file which has two purposes:

· To be able to use native functions & methods of the TMS

· To execute the partners solutions (tags) contained inside

It is possible, as it is often the case, to have several containers for the same site or even the same page.

The URL of each JavaScript Web Container file will be provided alongside the Container IDs and Container Names by a Commanders Act Consultant during the setup process.

Implementation of the containers on the page

Web 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.

The containers can be placed in different locations in the page source’s code depending on their use and your type of business.

Here’s a common example with 3 containers:

<head> container's location is usually used for AB test and should be load synchronously, to prevent flickering effect.

We recommended to implement all <body> containers asynchronously. Simply use the async attribute in the <script> element.

Important : the datalayer must be declared before your containers calls. Otherwise, the tags in the container will not be able to use the variables

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 Commanders Act Web Container on their own.

Testing

Via Browser 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 Web 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
        }
}

Definitions

Datalayer setup

A Commanders Act Data Layer is a JavaScript object that holds metadata of a website as properties to make it available to Tags. In the platform 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 Commanders Act 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 Commanders Act setup process, but you can find a list of common properties on .

Re-using an Existing Data Layer

In case a website already has a Data Layer installed it is possible to transform it into a Commanders Act 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.

The Data Layer needs to be filled with information before the Web 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 Commanders Act 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.

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.

Via Quality Assurance Tag

The Tag template Commanders Act - Data Layer QA in the Commanders Act 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.

Browser-side events setup

Commanders Act Events Triggers are onsite events that are used by Commanders Act users to dynamically execute Tags.

Definitions

Installation

Commanders Act allows to set up common Trigger automatically without the involvement of technical team (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 Commanders Act setup process, but you can find a list of native Trigger on .

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

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

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 Commanders Act Web 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.

Testing

Via Quality Assurance Tag

The Tag template Commanders Act - Event QA in the Commanders Act Tag library automatically outputs event 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. Another way, more technical: you can type in your console tc_arrray_events when the event is executed. The Data Layer of the event variables will be displayed.

AMP

Installation Instructions for Web container on AMP.

Accelerated Mobile Pages (AMP) use the Server-Side version of our TMS

AMP Definition

AMP, which stands for Accelerated Mobile Pages, is a technology issued from the open source Digital News Initiative (DNI) between Google and European publishers. AMP is a format allowing the creation of optimized mobile content in a bid to improve user experience.

If you wish to learn more about AMPs, click the following links:

[FR]

[EN]

Implementing Commanders Act on AMPs

AMP blocks synchronous JavaScript files called on your websites in order to increase mobile pages’ loading speed. For your Commanders Act container to be compatible, you need to adapt the way you set it up to be compliant with AMP’s requirements.

Below, you will find an example showing how to set up a Commanders Act container on your AMP pages. We recommend using the <amp-analytics> tag () to define your data layer and the container.

Important: This operation calls for Commanders Act’s API and thus requires that a server-side container be setup in Commanders Act’s user interface.

Setup example with analytics tag

AMPs also allow you to set up your tag management tool through an iframe. Please note that if the iframe has not loaded within 5 seconds, it will not be called. You will find below an a setup example through an iframe:

Setup example with iframe

Angular

Installation Instructions for Web container with Angular.

Commanders Act TMS offers dedicated Plug-Ins for all major Single Page Application (SPA) frameworks. Please refer to the Plug-In for detailed installation instructions for Angular.

Angular uses the Client-Side (web container) version of the TMS Commander's Act

It is also possible to send server-side events. Simply use a 'Web Container' source.

AngularJS

Installation Instructions for TagCommander with AngularJS.

Commanders Act TMS offers dedicated Plug-Ins for all major Single Page Application (SPA) frameworks. Please refer to the Plug-In for detailed installation instructions for AngularJS.

AngularJS uses the Client-Side (web container) version of the TMS Commander's Act

It is also possible to send server-side events. Simply use a 'Web Container' source.

React

Installation Instructions for Commanders Act Web Container with React.

Commanders Act offers dedicated Plug-Ins for all major Single Page Application (SPA) frameworks. Please refer to the Plug-In for detailed installation instructions for React.

React uses the Client-Side version of Commanders Act TMS.

SPA implementation guide

1. What is an SPA environment?

An SPA (Single Page Application) is a website or a web application that loads elements dynamically according to user actions rather than loading new pages after every interaction. Commanders Act web container offers functions allowing you to load all or a part of the container within an SPA environment, allowing you to call desired tags on every action performed by a user. These functions need to be implemented in your site’s source code by either your technical partner or by your own technical staff.

2.How to implement Commanders Act web container in an SPA environment?

2.1 Loading containers

Commanders Act web containers are loaded once upon page load within a Single Page Application Environment. In order to reload containers on user actions, you can use the following features:

tC.container.reload() : this function allows you to reload all the containers on a page. Elements shared by containers (deduplication calculation, external variables initialization, internal variables calculation, calculation of cookies dropped with data storage and the initialization of the Privacy cookie) are only loaded once to optimize performance.

This function allows to reload all of a page’s containers while excluding some of their elements. Elements to exclude need to be mentioned in the “exclusions” table. Ex: if you wish to reload the container without recalculating internal variables, you need to call this function: tC.container.reload({exclusions:["internalvars"]}) This function also allows to call the tC.event function that loads selected tags upon user action. The tC.event function is executed after the container elements reloading. label: specify the name you wish to call your function (ex : "click", "add_to_cart"…). targeted_element: DOM elements on which the event applies. {} if not necessary. event_variables: variables specific to the event. {} if not necessary.Ex:

tC.container.reload({events: {label1: [{target: document.getElementById('targeted_element'}, {"page_name":"", "product_id":""}]}})

tC.container_IDS_IDC.reload() : this function allows loading a single container (to do so, you will have to specify the site’s and the container’s ID) on a page that contains more than one.

IDS : Commanders Act site ID IDC : Commanders Act container ID

tC.container_IDS_IDC.reload({ exclusions: ["datastorage","deduplication","internalvars","privacy"], events: {label1: [{targeted_element},{event_variables}], label2: [{},{}]} })

This function allows loading a single container (to do so, you will have to specify the site’s and the container’s ID) on a page that contains more than one while excluding some of their elements. Elements to exclude need to be mentioned in the “exclusions” table, and event functions need to be mentioned in the “events” object, as for the tC.container.reload({exclusions:["datastorage","deduplication","internalvars","privacy"]}) function.

2.2 Loading tags

To load selected tags upon user action, you will need to implement this function:

tC.event.label() : this function allows loading selected tags upon user action.

label: specify the name you wish to call your function. Ex: implement the tC.event.step2_basket function if your wish to call specific tags on the 2nd step in the purchase cart. You can also set-up a “generic” function like tC.event.all on all of your virtual pages to call tags on all of your SPA sites (Analytics tags, for instance). You will then use perimeters and constraints from the Commanders Act interface to control other tags’ execution.

tC.event.label(this, {"page_name":"", "product_id":""}) : this function allows loading selected tags based on user action and to define variables specific to said action (ex : the name of a virtual page, a specific product id …).

2.3 Going further: Structure of a Commanders Act web Ccontainer

You will find below a list of all the elements that load inside the Commanders Act web container upon first load, as well as the tC.container.reload,(tC.container_IDS_IDC.reload()) and tC.event.XXX() functions that are called.

VueJS

Installation Instructions for Commanders Act Web Container with VueJS.

Commanders Act offers dedicated Plug-Ins for all major Single Page Application (SPA) frameworks. Please refer to the Plug-In documentation on GitHub for detailed installation instructions for VueJS.

VueJS uses the Client-Side version of Commanders Act TMS.

IOT & TV Apps

Installation Instructions for Commanders Act TMS for direct HTTP connections.

It is possible to send server-side events Commanders Act TMS container via a HTTP tracking API Source (e.g. for IOT and TV apps). Please refer to this page for more details

IOT & TV apps use the server-side events of TMS Commanders Act.

Web container setup

A web container is a JavaScript file which has two purposes:

· To be able to use native functions & methods of the TMS

· To execute the partners solutions (tags) contained inside

It is possible, as it is often the case, to have several containers for the same site or even the same page.

The URL of each JavaScript Web Container file will be provided alongside the Container IDs and Container Names by a Commanders Act Consultant during the setup process.

Implementation of the containers on the page

Web 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.

The containers can be placed in different locations in the page source’s code depending on their use and your type of business.

Here’s a common example with 3 containers:

<head> container's location is usually used for AB test and should be load synchronously, to prevent flickering effect.

We recommended to implement all <body> containers asynchronously. Simply use the async attribute in the <script> element.

Important : the datalayer must be declared before your containers calls. Otherwise, the tags in the container will not be able to use the variables

Installation of `<head>` Container

<!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

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

Installation via JavaScript Loaders

Testing

Via Browser 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 Web 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
        }
}

Definitions

Datalayer setup

Installation

Re-using an Existing Data Layer

In case a website already has a Data Layer installed it is possible to transform it into a Commanders Act 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.

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

Race Conditions

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

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

SPA implementation guide

1. What is an SPA environment?

2.How to implement Commanders Act web container in an SPA environment?

2.1 Loading containers

Commanders Act web containers are loaded once upon page load within a Single Page Application Environment. In order to reload containers on user actions, you can use the following features:

tC.container.reload() : this function allows you to reload all the containers on a page. Elements shared by containers (deduplication calculation, external variables initialization, internal variables calculation, calculation of cookies dropped with data storage and the initialization of the Privacy cookie) are only loaded once to optimize performance.

tC.container.reload({events: {label1: [{target: document.getElementById('targeted_element'}, {"page_name":"", "product_id":""}]}})

tC.container_IDS_IDC.reload() : this function allows loading a single container (to do so, you will have to specify the site’s and the container’s ID) on a page that contains more than one.

IDS : Commanders Act site ID IDC : Commanders Act container ID

tC.container_IDS_IDC.reload({ exclusions: ["datastorage","deduplication","internalvars","privacy"], events: {label1: [{targeted_element},{event_variables}], label2: [{},{}]} })

2.2 Loading tags

To load selected tags upon user action, you will need to implement this function:

tC.event.label() : this function allows loading selected tags upon user action.

tC.event.label(this, {"page_name":"", "product_id":""}) : this function allows loading selected tags based on user action and to define variables specific to said action (ex : the name of a virtual page, a specific product id …).

Setup guides for developers

Web container setup

Implementation of the containers on the page

Installation of <head> Container

Installation of <body> Container

Installation via JavaScript Loaders

Testing

Via Browser Console

Definitions

Datalayer setup

Installation

Re-using an Existing Data Layer

Race Conditions

Data Layer Naming Convention

Testing

Via JavaScript Console

Via Quality Assurance Tag

Browser-side events setup

Definitions

Installation

Trigger Data Layer Properties

Trigger Error Handling

Testing

Via Quality Assurance Tag

AMP

AMP Definition

Implementing Commanders Act on AMPs

Setup example with analytics tag

Angular

AngularJS

React

SPA implementation guide

1. What is an SPA environment?

2.How to implement Commanders Act web container in an SPA environment?

2.1 Loading containers

2.2 Loading tags

2.3 Going further: Structure of a Commanders Act web Ccontainer

VueJS

IOT & TV Apps

Setup guides for developers

Web container setup

Implementation of the containers on the page

Installation of <head> Container

Installation of <body> Container

Installation via JavaScript Loaders

Testing

Via Browser Console

Definitions

React

AMP

AMP Definition

Implementing Commanders Act on AMPs

Setup example with analytics tag

Datalayer setup

Installation

Re-using an Existing Data Layer

Race Conditions

Data Layer Naming Convention

Testing

Via JavaScript Console

Via Quality Assurance Tag

Browser-side events setup

Definitions

Installation

Trigger Data Layer Properties

Trigger Error Handling

Testing

Via Quality Assurance Tag

AngularJS

Angular

IOT & TV Apps

VueJS

SPA implementation guide

1. What is an SPA environment?

2.How to implement Commanders Act web container in an SPA environment?

2.1 Loading containers

2.2 Loading tags

2.3 Going further: Structure of a Commanders Act web Ccontainer

Installation of `<head>` Container

Installation of `<body>` Container

Installation of `<head>` Container

Installation of `<body>` Container