All pages
Powered by GitBook
1 of 11

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

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.

Setup guides for developers

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

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 documentation on GitHub 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 documentation on GitHub 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 documentation on GitHub for detailed installation instructions for React.

React 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 for more details

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

this page

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:

A/B-test (optional)
In the <head>

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

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

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

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

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.

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:

Browser-side events setup

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

Metric
Description

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. e.g. "55.16".

Analytics

At the beginning of <body>

Marketing

At the end of </body >

Account ID

Unique account ID of your workspace on our platform. Also called "Site ID". Log in into your Commanders Act account and look for the first numeric value in your address bar. e.g. with "https://app.commandersact.com/en/1234/", your account identifier is "1234".

Container ID

Unique ID of the Container within your account. e.g. "15".

Container Name

Label of the Container. Can be configured in the "container settings" of TMS. e.g. "Header Container".

Container Filename

Name of the Container JavaScript file, can be configured in the "container settings" of TMS. e.g. "tc_header_21.js".

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

Installation of <body> Container

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

Definitions

Container URL

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="{{ head_container_URL }}"></script>
        (...)
    </head>
    (...)
</html>
<!DOCTYPE html>
<html>
    (...)
    <body>
        (...)
        <script src="{{ body_container_URL }}"></script>
    </body>
</html>
{
    1234: { // Commanders Act 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
        }
}
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 this page.

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:

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.

Trigger Label

Label for an event that is used by Commanders Act 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

Definitions

Installation

tC.event.{{ Trigger Label }}(this, {{ Trigger Data Layer }});
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

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

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.
if (tC && tC.event && typeof tC.event.add_to_basket === "function") {
    tC.event.add_to_basket(this, { product_id: "12345" });
}

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] https://www.ampproject.org/fr/learn/about-amp/

[EN] https://www.ampproject.org/learn/about-amp/

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.

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

Setup example with analytics tag

https://www.ampproject.org/docs/reference/components/amp-analytics
<!doctype html>
<html amp lang=”en”>
<head>
<meta charset=”utf-8″>
<title>Commanders Act – AMP Analytics</title>
<link rel=”canonical” href=”http://example.ampproject.org/article-metadata.html” />
<meta name=”viewport” content=”width=device-width,minimum-scale=1,initial-scale=1″>
<!– Mandatory execution of the AMP Analytics Script “https://cdn.ampproject.org/v0/amp-analytics-0.1.js” –> 
<script async custom-element=”amp-analytics”
src=”https://cdn.ampproject.org/v0/amp-analytics-0.1.js“></script>
<style>body {opacity: 0}</style><noscript><style>body {opacity: 1}</style></noscript>
<script async src=”https://cdn.ampproject.org/v0.js”></script>
</head>
<body
<amp-analytics id=”commandersact”>
<!– JSON data structure containing the TagCommander data layer –> 
<script type=”application/json”>
{
“vars”: {
“tC_SiteID”: “3503”,
“tC_ContainerID”: “1”,
“env_template” : “homepage”,
“env_work” : “prod”,
“env_device” : “m”,
“env_country” : “IT”,
“page_name” : “amp_homepage”,
“user_id” : “”,
“user_newcustomer” : “”,
“order_id” : “”
},
<!– Call to Commanders Act’s API (server-side) –> 
“requests”: {
“tC_BaseURL“: “//serverside${tC_SiteID}.tagcommander.com/${tC_ContainerID}/”,
<!– Page variables mentioned in the “tC_PageTrack” element –> 
“tC_PageTrack“: “${tC_BaseURL}?&env_template=${template}&env_work=${work_environment}&env_device=${device}&env_country=${country}&page_name=${page_name}&user_id=${user_id}&user_newcustomer=${newcustomer}&order_id=${order_id}”,
<!– Event variables mentioned in the “tC_EventTrack” element. Note: “scroll” and other such variables are natively proposed in AMP pages–> 
“tC_EventTrack“: “${tC_PageTrack}&scrollY=${scrollTop}&scrollX=${scrollLeft}&height=${availableScreenHeight}&width=${availableScreenWidth}&scrollBoundV=${verticalScrollBoundary}&scrollBoundH=${horizontalScrollBoundary}${eventLabel}”
},
<!– Additional parameters mentioned in the “extraUrlParams” element. Note: the clientId function creates a unique ID per visitor (different from the regular TCIDs)–> 
“extraUrlParams”: {
“TCID_AMP”: “${clientId(TCID_AMP)}”,
“path”: “${ampdocUrl}”,
“type”: “${type|default:page}”,
“platform”: “AMP”,
“r”: “${random}”
},
<!– Execution of Commanders Act hits on the “triggers” element. “Pageview” sends the hit to the page viewed, the “clickPings” trigger sends the hit to an event defined in the “selector” –>
“triggers”: {
“pageview”: {
“on”: “visible”,
“request”: “tC_PageTrack”,
“vars”: {
“type”: “page”
}
},
“clickPings”: {
“on”: “click”,
“selector”: “.tC_events”,
“request”: “tC_EventTrack”,
“vars”: {
“type”: “event”
}
}
}
}
</script>
</amp-analytics>
<h1 id=”header”>AMP Page</h1>
<!– data-vars-event-label2 allows to collect additional variables, such as event variables –>
<span id=”event-test” class=”tC_events” data-vars-event-label2=”22″>
Click here to generate an event
</span>
</body>
<!doctype html>
<html amp lang=”en”>
<head>
<meta charset=”utf-8″>
<title>Commanders ACT – Serverside – AMP Analytics</title>
<link rel=”canonical” href=”http://example.ampproject.org/article-metadata.html” />
<meta name=”viewport” content=”width=device-width,minimum-scale=1,initial-scale=1″>
<!– Mandatory execution of the AMP iframe script “https://cdn.ampproject.org/v0/amp-iframe-0.1.js ” –>
<script async custom-element=”amp-iframe” src=”https://cdn.ampproject.org/v0/amp-iframe-0.1.js”></script>
<style>body {opacity: 0}</style><noscript><style>body {opacity: 1}</style></noscript>
<script async src=”https://cdn.ampproject.org/v0.js”></script>
</head>
<body>
<!– Call to the TagCommander iframe “https://academy.commandersact.com/AMP/iframe.php” containing the data layer variables. Note: the iframe must belong to a different domain from that of the website (except if the allow-same-origin parameter is added) and be https –>
<amp-iframe width=1 height=1 src=”https://academy.commandersact.com/AMP/iframe.php? env_template=homepage&env_work=prod&env_device=m&env_country=IT&page_name=amp_homepage&user_id=&user_newcustomer=&order_id=” sandbox=”allow-scripts allow-same-origin” layout=”fixed” frameborder=”0″>
<!– Adding content to the iframe is mandatory (a pixel in this case)–>
<amp-img src=”https://academy.commandersact.com/AMP/pixel.gif” height=1 width=1 layout=”fill” placeholder></amp-img>25
</amp-iframe>
<h1 id=”header”>AMP Page</h1>
<span id=”event-test” class=”tC_events” data-vars-event-label2=”22″>
Click here to generate an event
</span>
</body>
</html>

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.

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

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.

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 …).

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.

Container element
Definition
1st container load
tC.container.rel oad() function
tC.container_IDS_IDC.reload() function
tC.event.XXX() function

no

External variables initialization

They define all external variables that do not already exist

yes

yes

yes

no

Dynamic JS 1

Calls an external JavaScript file prior to the internal variables’ declaration

yes

no

no

no

Static JS 1

Calls custom JavaScript code prior to the internal variables’ declaration

yes

no

no

no

Internal variables

Calculates internal variables

yes

yes

yes

no

Dynamic JS 2

Calls an external JavaScript file after the external variables’ declaration

yes

no

no

no

Static JS 2

Calls an external JavaScript file after the internal variables’ declaration

yes

no

no

no

Data storage

Calculates the value of cookies created with the "data storage" module

yes

yes

yes

no

"Container loaded" & "DOM ready" & "Clicks"& "Form submission " & "Scroll" tags + rules

Executes tags called on the "Container loaded", "DOMready", "Clicks","Form submission" and"Scroll" triggers, as well as on the rules associated to the

yes

no

no

no

​

container’s first load.

​

​

​

​

"Custom" tags + rules

Executes tags called on the "Custom"triggers, as well as on the rules associated to the container’s loading or reloading.

yes

yes

yes

yes

Events + rules

Executes events triggered on the previous tc_events function

yes

no

no

no

Privacy

Re-initializes the Privacy cookie to take into account users’ choices.

yes

yes

yes

No

Tag Hierarchy

Identifies piggybacked tags (tags sideloaded by other tags in the"TagPerformanc e" module)

yes

no

no

no

Event listener

Reloads event listeners (which allow to track actions performed by any userbrowsing the site (clicks, scrolls …))

yes

no

no

no

Deduplication functions

They identify thevisitor’s traffic source

yes

Yes (once loaded)

2.2 Loading tags

2.3 Going further: Structure of a Commanders Act web Ccontainer

yes

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 this page.

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.

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

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.

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.

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

Via Quality Assurance Tag

<!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>
{
    env_template: "homepage",
    env_work: "prod",
    page_name: "Homepage",
    page_keywords: ["homepage", "home", "entrypage", "index"],
    product_name: "",
    (…)
}