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.
1
<!DOCTYPEhtml>
2
<html>
3
<head>
4
<metacharset="UTF-8"/>
5
<scriptsrc="{{ head_container_URL }}"></script>
6
(...)
7
</head>
8
(...)
9
</html>
Copied!
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.
1
<!DOCTYPEhtml>
2
<html>
3
(...)
4
<body>
5
(...)
6
<scriptsrc="{{ body_container_URL }}"></script>
7
</body>
8
</html>
Copied!
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:
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.
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.
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.
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.
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:
1
tC.event.{{ Trigger Label }}(this,{{ Trigger Data Layer }});
Copied!
A typical example is an Add to basket event where the product id of the selected product is sent with the event:
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.
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.