Technical Docs Contentsquare Web Tracking Implementation

Contentsquare Web Tracking Implementation

The following instructions will go through the essential steps you'll need to take in order to tailor the Contentsquare implementation around your needs and start using our solution as soon as possible.

📚 For further reference, see the Tag reference documentation

The Main Tracking Tag

The Contentsquare Main Tracking Tag or Main tag is the core 'pixel' or 'code snippet' that needs to be implemented on your domain in order to collect analytics data. It can be implemented through a TMS or on the site's template. Find step-by-step guides below.

Prior to the implementation, you need to gather the following information:

  • A Contentsquare Tag ID will be provided after kicking off the Contentsquare partnership. This 13-character unique ID can be use only on agreed domains — no data will be sent from elsewhere.

  • You can provide up to 20 custom variables to enrich the analysis context with details about the pages or the user. They're usually collected from your datalayer or any other JavaScript object implemented throughout the site.

Google Tag Manager (Template)

  1. Open your container and go to the templates section.

  2. Select Search Gallery.

  3. Type in contentsquare and select the Contentsquare - Main tag option.

  4. Click Add to workspace.

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag.

  7. Configure it by selecting the top-right button.

  8. Search for contentsquare and select the Contentsquare - Main tag template that you've previously added to your container.

  9. Give a title to the tag and input your Tag ID in the dedicated field. If you'd like to configure any Custom Variables, do so by selecting:

    • The index, from 1 to 20 - unique numbers only,
    • The name,
    • The value itself, which will be taken from one of your GTM Variables.

    Select the trigger that best suits your needs.

    We suggest All Pages, as long as your selected variables will be populated by then.

  10. (Optional) Mask Personal Data within the GTM GUI.

    Select the appropriate Personal Data masking method, depending on the type of personal information you’re looking to mask:

    • Define CSS Selectors for text nodes.
    • CSS Selectors and Data Attributes for element attributes.

  11. Save your changes and go back to your container. You should now see both the template and the newly created tag.

Google Tag Manager (Custom HTML)

  1. Add a new tag on your workspace.

  2. Select "Choose a tag type to begin setup...".

  3. In the list, pick the "Custom HTML" tag.

  4. Depending on your data layer availability, take a look at the following code examples and populate it with the information required:

    • Implementing the tag and pushing data layer variables to Contentsquare:

      <script>
(function () {
    window._uxa = window._uxa || [];
    try {
        window._uxa.push(['setCustomVariable', 1, 'Sample Variable', {{your-GTM-variable-here}}, 3]);
    } catch(e){}
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>

    • Implementing the tag without pushing data layer variables to Contentsquare:

      <script>
(function () {
    window._uxa = window._uxa || [];
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>

  5. Select "Choose a trigger to make this tag fire...".

  6. In the list, pick the "All pages" trigger, provided the Datalayer will have been loaded before firing our tag.

  7. Name your tag (for instance Contentsquare Main Tag), then click "Save".

Tealium

  1. Add a new tag to your containers by choosing "Content Square UX Analytics "

  2. Add your "TAG ID" and click "next" twice, keeping the default configuration. If you do not have custom variables, click "Finish" and the installation is over.

  3. (Optional) Add custom variables:

    • Choose a datalayer Variable in the UDO list and select Select Destination
    • Select "Custom"
    • Add a variable Name
    • Click Add
    • Click Close and the mapped variable will appear

  4. Click "Finish" or repeat STEP 3 for additional variables.

Adobe Launch

Installing the Contentsquare extension

  1. Search for Contentsquare within Extensions and select Install.

  2. Enter your Tag ID, as provided by your Contentsquare Implementation team.

    Should you want to pass Contentsquare any information via custom variables, you can do so by selecting Add New Variable and filling in the related input fields. Use Data Elements in the value fields, as they are the Launch built-in method of passing information between extensions. You can also remove custom variables by selecting the 'minus' icon.

  3. (Optional) Select Add PII Masking.

  4. Upon activating PII Masking, select the appropriate masking method, depending on the type of personal information you’re looking to mask:

    • Masking textual PII using CSS selectors: Make sure that your CSS selectors are valid.

    • If non-textual personal information needs to be masked, use the below text box and template:

  5. Save your changes to your working library and move to the next step.

Firing the Main Tag

Head over to the Rules tab, selecting Add Rule.

Event Configuration

Depending on your needs, select the event to be used from the core extension.

Default implementation - page bottom and DOM ready

Take a look at some of the viable examples below:

Action Configuration

Select the Main Tracking Tag Installation action from the Contentsquare extension

If you don't need to further amend the path or the queries sent, you can leave the action as it is and press 'Keep Changes'

Should you need to override the path and/or the query, you can do so by selecting the element and writing the string to be used as a substitute. You can also create Data Elements and use them in these fields

Once you're done, your new rule should look similar to the following

You can now press save and move on to the next rule.

Commanders Act

  1. Add a new tag to your containers by choosing Contentsquare (Builder).

  2. Set the right Contentsquare template by selecting Main.

  3. Enter your previously provided Tag ID.

  4. (Optional) To add custom variables, select Yes under "Add customs variables" and supply:

    • The name
    • The scope: 2 for visit, 3 for page, 4 for nextPageOnly.
    • The value, which may be one of your Commanders Act variables.

  5. Name your tag - for instance Contentquare Main Tag, and click Save.

Your tag is ready to be deployed.

Shopify

Base configuration

  1. Within the main menu, select Online Store > Themes, then click the Actions drop-down menu, and Edit Code.

  2. Under Layout, select the theme.liquid file.

  3. Within the code editor, scroll down to the closing </head> tag.

  4. Copy the code below and replace YOUR_TAG_ID with your Contentsquare Tag ID:

    <!-- Contentsquare Tags Start -->
<script type="text/javascript">
//Contentsquare Main Tracking Tag
(function() {
    window._uxa = window._uxa || [];
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname + window.location.hash.replace('#', '?__')]);
        var mt = document.createElement("script");
        mt.type = "text/javascript";
        mt.async = true;
        mt.src = "//t.contentsquare.net/uxa/YOUR_TAG_ID.js";
        document.getElementsByTagName("head")[0].appendChild(mt);
    } else {
        window._uxa.push(['trackPageview', window.location.pathname + window.location.hash.replace('#', '?__')]);
    }
})();
</script>
<!-- Contentsquare Tags End -->

  5. Paste the code above the closing </head> tag.

  6. Click Save.

Track the Checkout flow with Contentsquare

If you do no have a Shopify Plus account and still want to track orders that were processed then you can add the code to the thank you page after a transaction has been completed. This way, you can capture ecommerce data then by doing the following:

  1. Click Settings.

  2. In the overlay that appears select Checkout and accounts.

  3. Scroll down to the Order status page section.

  4. In the Additional scripts field, insert the same code snippet that you inserted in the theme.liquid file:

  5. Click Save.

Sending custom variables

To send custom variables to Contentsquare, define them before the Contentsquare main tag.

Modify the keys and values to your needs: you can get values from your Liquid Objects or Liquid Tags.

<script type="text/javascript">
    //Contentsquare Send Custom Variables
    window._uxa = window._uxa || [];
    window._uxa.push(['setCustomVariable', 1, "Insert Custom Key 1", "Insert Custom Vale : " + {{ custom_tag.value1 }}]);
    window._uxa.push(['setCustomVariable', 2, "Insert Custom Key 2", "Insert Custom Vale : " + {{ custom_tag.value2 }}]);
    window._uxa.push(['setCustomVariable', 3, "Insert Custom Key 1", "Insert Custom Vale : " + {{ custom_tag.value3 }}]);
 
    //Contentsquare Main Tracking Tag
    (function () {
        window._uxa = window._uxa || [];
        if (typeof CS_CONF === 'undefined') {
            window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
            var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
            mt.src = '//t.contentsquare.net/uxa/769238b6e1309.js';
            document.getElementsByTagName('head')[0].appendChild(mt);
        }
        else {
            window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
        }
})();
</script>

For more information, see the setCustomVariable command.

Sending dynamic variables

You can send dynamic variables at any point in the pageview, they do not need to be set before the Contentsquare tag is loaded.

Modify the keys and values to your needs: you can get values from your Liquid Objects or Liquid Tags.

<script type="text/javascript">
    // Contentsquare Send Artificial Pageviews
    document.getElementById("AddToCart").addEventListener('click', function() {
        window._uxa = window._uxa || [];
        window._uxa.push(["setPath", "Added_to_cart_" + {{ custom_tag.value }}]);
        window._uxa.push(["trackPageview"]);
 
        window._uxa = window._uxa || [];
        window._uxa.push(["trackDynamicVariable", {key: "Added to cart", value: {{ custom_tag.value }}}]);
    });
</script>

For more information, see the trackDynamicVariable command.

Custom HTML

You just need to add the following lines of code on every page you want to analyze, at the end of the body marker.

<script>
(function () {
    window._uxa = window._uxa || [];
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>

In order to collect custom variables from your datalayer, take a look at the following code example:

<script>
(function () {
    window._uxa = window._uxa || [];
    try {
        if (typeof dataLayer !== 'undefined') {
            for (var i = 0; i < dataLayer.length; i++) {
               window._uxa.push(['setCustomVariable', 1, 'Sample Variable', dataLayer[i].sampleVariable, 3]);
            }
        }
    } catch(e){}
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>

The Main Tag should be loaded as soon as possible, once all the variables that need to be accessed have been populated.

Browse the Tag reference documentation for more information.

Artificial Pageviews

Artificial pageviews are to be used when:

  • An action completely changes the content displayed on the page without refreshing it and changing its URL (i.e Ajax requests);
  • The site is built with a Single Page Application (SPA) and any related frameworks (i.e. React, Angular);
  • The user gets redirected to another step of a funnel without refreshing the page;
  • The site re-routes all the URL changes without refreshing the page;
  • The site is built as a Progressive Web App (PWA);
  • Important Modal/Popup windows are displayed.

Full technical documentation about firing artificial pageviews...

Stable URLs - Modal windows and artificial pageviews tracking

For tracking modal windows or events that don't change the URL structure, you'll need to use the Contentsquare Trackpageview functionality by following these methods and binding them to the correct action (button click/event trigger).

Dynamic URLs - Single Page Applications and History Change

In the event of the URL structure being changed on each view change, we can keep track of this by simply firing the Main Tag again: the tag will automatically detect that it was previously put in place on the site and fire a new pageview instead.

Google Tag Manager (Template)

[tab] Stable URLs

  1. Open your container and go to the templates section

  2. Select Search Gallery

  3. Type in contentsquare and select the Contentsquare - Artificial Pageview option

  4. Click Add to workspace

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag

  7. Configure it by selecting the top-right button

  8. Type in contentsquare and select the Contentsquare - Artificial Pageview option

  9. Select the tag and configure:

    • Select the Free text option and enter the value under Artificial Pageview value.
    • If there's a pop-up on your website and you need to deploy APV, then select Use for the opening of a popup in the drop-down.

[tab] Dynamic URLs

  1. Amend the Main tag configuration by adding a new trigger to it.

  2. Create a new trigger

  3. Select "Choose a trigger type to begin setup...".

  4. In the list, select the "History Change" trigger.

  5. Save your trigger.

  6. Select the "Save" button on the top right.

Google Tag Manager (Custom HTML)

[tab] Stable URLs

  1. Select "Choose a tag type to begin setup...".

  2. In the list, pick the "Custom HTML" tag.

  3. Write the snippet to be fired in the HTML field. It should be similar to this:

    <script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['setQuery', location.search + (location.search ? '&' : '?') + 'cs-popin-dedicated_query_string']);
    window._uxa.push(['trackPageview', window.location.pathname + window.location.hash.replace('#', '?__')]);
    window._uxa.push(['setQuery', location.search]);
</script>

  4. Select "Choose a trigger to make this tag fire...".

  5. Create a new trigger to make this tag fire

  6. Select "Choose a trigger type to begin setup...".

  7. In the list, pick the "All Elements" trigger.

  8. Check "Some Clicks"

  9. Select "Click Element", "matches CSS selector" and enter a valid CSS filter corresponding to the element you want to track.

    For example the valid CSS for:

    <button class="btn btn primary"> Submit </button>

    Will be:

    .btn.btn.primary

[tab] Dynamic URLs

  1. Amend the Main tag configuration by adding a new trigger to it.

  2. Create a new trigger

  3. Select "Choose a trigger type to begin setup...".

  4. In the list, select the "History Change" trigger.

  5. Save your trigger.

  6. Select the "Save" button on the top right.

Tealium

[tab] Stable URLs

Assign the event you might already have in place to the a custom HTML snippet and write the snippet to be fired in the HTML field. It should be similar to this:

<script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['setQuery', location.search + (location.search ? '&' : '?') + 'cs-popin-dedicated_query_string']);
    window._uxa.push(['trackPageview', window.location.pathname + window.location.hash.replace('#', '?__')]);
    window._uxa.push(['setQuery', location.search]);
</script>

[tab] Dynamic URLs

Create (or select an already existing) event that occurs on each history change or view re-routing. Assign this event to the Contentsquare extension.

Adobe Launch

[tab] Stable URLs

Artificial Pageviews

When setting up the rule, make sure to target the specific event or condition needed. For instance, for an add to bag action, you could either follow the click route:

Or the custom event route:

Once you've chosen the desired event, you can select the Artificial Pageview tracking action from the Contentsquare extension.

Depending on the pageview you need to track, you can:

  • Specify the query to be passed to the Contentsquare servers,

  • Capture the current URL automatically, by leaving the input field empty.

[tab] Dynamic URLs

In the event of a SPA implementation, if the path/query automatically changes on each re-routing, utilise the built-in history change event to fire the CS tag on each of these occurrences.

Commanders Act

  1. To add a new event, go to the "EDIT" step, and click "ADD EVENT" (1):

    A configuration window will appear, with several fields:

    • (1) "Name": Name of the event you wish to add
    • (2) "Id": The event’s ID (to be completed only if you know it and want to trigger the event based on its ID; otherwise, leave the field empty, and it will be generated automatically by Commanders Act)
    • (3) JavaScript code: Area where the event’s JavaScript code is entered
    • (4) "Use Tag Cleaner": Feature allowing you to "correct" the event (rewrites it in order to avoid JavaScript errors and makes it compatible with the container’s code)

  2. Click "ADD" to add your event to the container.

  3. Go to the tag library. Once there:

    1. Write "Event Injection" in the search engine
    2. Select the tag
    3. Add the tag

In case of tracking pageviews with Contentsquare, the code to be deployed should follow this guideline:

window._uxa = window._uxa || [];
window._uxa.push(['trackPageview', <PATH_TO_SEND> ]);

(4) Go to your website; place the cursor on the element you wish to place an event on and do a right click. In the menu that opens up, select "Inspect Element". (5) In the console, once the element is highlighted, right-click again. (6) Choose "copy" from the menu. (7) > "Copy Selector".

(8) If you know the element’s ID (starting with a #, copy and paste it in the #CSS_PATH# field).

(9) If you do not know or cannot find the ID, copy and paste the element’s information starting with "#" and replace " > "(space>space) with a single space in the code line.

(10) Copy and paste the line in the interface’s #CSS_Path# field.

Now enter the ID of the event you wish to summon in the corresponding field.

Proceed to the deployment step as you do with other tags.

Shopify

  1. Within the main menu, select Online Store > Themes, then click the Actions drop-down menu, and Edit Code.

  2. Open the relevant Liquid file where you want to trigger an artificial pageview based on your own JavaScript logic. You can put this in the main theme.liquid file or in a specific Liquid file.

    Let’s say you want to trigger this artificial pageview only when a certain action takes place like when an item is added to the cart. You would need to wrap this code inside your own condition, callback function, or event listener.

  3. In the snippet below, replace *path_to_send* with your unique path.

    <script type="text/javascript">
window._uxa = window._uxa || [];
window._uxa.push(['trackPageview', *path_to_send* ]);
</script>

    You either hard-code a static value for the path like Added_to_cart or use Shopify’s Liquid Objects/Liquid Tags to grab the dynamic data from it like below:

    <script type="text/javascript">
// Contentsquare Send Artificial Pageviews
document.getElementById("AddToCart").addEventListener('click', function() {
    window._uxa = window._uxa || [];
    window._uxa.push(["trackPageview", "Added_to_cart_" + {{ custom_tag.value}}])
});
</script>

  4. Insert this code after the main tracking tag block.

    The end result of adding this code into the Liquid file:

    <!-- Contentsquare Tags Start -->
<script type="text/javascript">
// Contentsquare Main Tracking Tag
(function() {
    window._uxa = window._uxa || [];
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement("script");
        mt.type = "text/javascript";
        mt.async = true;
        mt.src = "//t.contentsquare.net/uxa/769238b6e1309.js";
        document.getElementsByTagName("head")[0].appendChild(mt);
    } else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
});
</script>
 
<script type="text/javascript">
// Contentsquare Send Artificial Pageviews
document.getElementById("AddToCart").addEventListener('click', function() {
    window._uxa = window._uxa || [];
    window._uxa.push(["trackPageview", "Added_to_cart_" + {{ custom_tag.value}}])
});
</script>

  5. To modify the entire path that is sent, use the setPath command:

    <script type="text/javascript">
    // Contentsquare Send Artificial Pageviews
    document.getElementById("AddToCart").addEventListener('click', function() {
        window._uxa = window._uxa || [];
        window._uxa.push(["setPath", "Added_to_cart_" + {{ custom_tag.value }}]);
        window._uxa.push(["trackPageview"]);
    });
</script>

    For more information, see the setPath command.

  6. To modify only the query string, use the setQuery command:

    <script type="text/javascript">
    // Contentsquare Send Artificial Pageviews
    document.getElementById("AddToCart").addEventListener('click', function() {
        window._uxa = window._uxa || [];
        window._uxa.push(["setQuery", "Added_to_cart_" + {{ custom_tag.value }}]);
        window._uxa.push(["trackPageview"]);
    });
</script>

For more information, see the setQuery command.

Custom HTML

[tab] Stable URLs

For instance, in case you wanted to keep track of the popup window appearing when adding an item to the cart:

<script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['setQuery', location.search + (location.search ? '&' : '?') + 'cs-popin-dedicated_query_string']);
    window._uxa.push(['trackPageview', window.location.pathname + window.location.hash.replace('#', '?__')]);
    window._uxa.push(['setQuery', location.search]);
</script>

[tab] Dynamic URLs

With custom variables
<script>
(function () {
    window._uxa = window._uxa || [];
    try {
        if (typeof dataLayer !== 'undefined') {
            for (var i = 0; i < dataLayer.length; i++) {
               window._uxa.push(['setCustomVariable', 1, 'Sample Variable', dataLayer[i].sampleVariable, 3]);
            }
        }
    } catch(e){}
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>
Without custom variables
<script>
(function () {
    window._uxa = window._uxa || [];
    if (typeof CS_CONF === 'undefined') {
        window._uxa.push(['setPath', window.location.pathname+window.location.hash.replace('#','?__')]);
        var mt = document.createElement('script'); mt.type = 'text/javascript'; mt.async = true;
        mt.src = '//t.contentsquare.net/uxa/{{YOUR_TAG_ID}}.js';
        document.getElementsByTagName('head')[0].appendChild(mt);
    }
    else {
        window._uxa.push(['trackPageview', window.location.pathname+window.location.hash.replace('#','?__')]);
    }
})();
</script>

Dynamic variables tag

Dynamic vars are additional information on the session that can be used to segment users.

For example, they can include information on the A/B Test variations displayed to the current user.

Unlike custom vars, dynamic vars can be sent at any time during a session and do not require to send a pageview.

For more information, see Dynamic vars.

Google Tag Manager (Template)

  1. Open your container and go to the templates section.

  2. Select Search Gallery.

  3. Type in contentsquare and select the Contentsquare - Dynamic variables option.

  4. Click Add to workspace.

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag.

  7. Configure it by selecting the top-right button.

  8. Search for contentsquare and select the Contentsquare - Dynamic variables template that you've previously added to your container.

  9. Give a title to the tag and input your Tag ID in the dedicated field.
    For each dynamic variable, enter:

    • The key
    • The value
    • The type - Number or String.

    Select the trigger that best suits your needs.

  10. Save your changes and go back to your container. You should now see both the template and the newly created tag.

Adobe Launch

  1. Within Tag properties, select Rules > Add Rule.

  2. Specify a name, events, and conditions.

  3. Add an Action with the following settings:

    • Extension: Contentsquare,
    • Action Type: Dynamic Variables,
    • Name: Contentsquare - Dynamic Variable tracking.

  4. On the right-hand side, select Add New Variable.

  5. For each dynamic variable, enter:

    • The key
    • The value
    • The type - Number or String.

  6. Select Keep Changes > Save.

ETR Event tag

The ETR event tag allows to trigger ETR events to save the recorded session of the visitor.

For more information, see Events Handling.

Google Tag Manager (Template)

  1. Open your container and go to the templates section.

  2. Select Search Gallery.

  3. Type in contentsquare and select the Contentsquare - ETR Event option.

  4. Click Add to workspace.

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag.

  7. Configure it by selecting the top-right button.

  8. Search for contentsquare and select the Contentsquare - ETR Event template that you've previously added to your container.

  9. Give a title to the tag and input your Tag ID in the dedicated field.

  10. Enter the event name.

  11. Select the event type: Page Level or Session Level.

    Select the trigger that best suits your needs.

  12. Save your changes and go back to your container. You should now see both the template and the newly created tag.

Adobe Launch

  1. Within Tag properties, select Rules > Add Rule.

  2. Specify a name, events, and conditions.

  3. Add an Action with the following settings:

    • Extension: Contentsquare,
    • Action Type: ETR Event,
    • Name: Contentsquare - ETR Event.

  4. On the right-hand side, enter the event name.

  5. Select the event type: Page Level or Session Level.

  6. Select Keep Changes > Save.

Page Events tag

This tag allows for Page events to be sent to Contentsquare.

Page events are additional information on the session that can be used to segment sessions.
Similar to dynamic variables, they can be sent at any time during a session.

For more information, see Page Events.

Google Tag Manager (Template)

  1. Open your container and go to the templates section.

  2. Select Search Gallery.

  3. Type in contentsquare and select the Contentsquare - Page Events option.

  4. Click Add to workspace.

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag.

  7. Configure it by selecting the top-right button.

  8. Search for contentsquare and select the Contentsquare - Page Events template that you've previously added to your container.

  9. Give a title to the tag and input your Tag ID in the dedicated field.

  10. Enter the event name.

  11. (Optional) If needed, add additional page events.

    Select the trigger that best suits your needs.

  12. Save your changes and go back to your container. You should now see both the template and the newly created tag.

Adobe Launch

  1. Within Tag properties, select Rules > Add Rule.

  2. Specify a name, events, and conditions.

  3. Add an Action with the following settings:

    • Extension: Contentsquare,
    • Action Type: Page Events,
    • Name: Contentsquare - Page Event.

  4. On the right-hand side, enter the event name.

  5. Select Keep Changes > Save.

The E-commerce tag

The e-commerce tag is used to keep track of the e-commerce transactions happening on the site and empower analysis with revenue-related metrics.

It needs to be fired a single time on the confirmation page, after the transaction has been finalised, and needs the following mandatory parameters in order to function:

  • Transaction ID, which is the unique identifier for that transaction
  • Revenue, which is the total amount of the purchase

You can also include the following optional parameters:

Google Tag Manager (Template)

  1. Open your container and go to the templates section

  2. Select Search Gallery

  3. Type in contentsquare and select the Contentsquare - E-commerce data option

  4. Click Add to workspace

  5. Confirm your choice by selecting Add

  6. Go to the Tags section and click the New button to create a new tag

  7. Configure it by selecting the top-right button

  8. Search for contentsquare and select the Contentsquare - E-commerce data template that you've previously added to your container.

  9. Give a title to the tag and add your GTM Variables to the Transaction IDs and Revenue fields.

    Make sure to select a trigger that fires only on the confirmation page, or on all the pages that are needed to keep track of transactions, on which your variables are going to be populated.

  10. If you would like to send Contentsquare the currency value as well, fill in the optional parameters section.

  11. Save your changes and go back to your container. You should now see both the template and the newly created tag.

Google Tag Manager (Custom HTML)

  1. Create a new tag and paste the following code in the HTML field:

    <script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['ec:transaction:create', {
        'id': '{{YOUR ID HERE}}',
        'revenue': '{{YOUR REVENUE HERE}}',
        'currency':'{{CURRENCY ISO CODE HERE}}'
    }]);
    window._uxa.push(['ec:transaction:send']);
</script>

  2. Inside the script, replace all the placeholder variables with your GTM values (using the double brace notation: {{transaction id}}, {{transaction revenue}}).

    These variables must be available in the "Variables" section of Google Tag Manager.

  3. In the trigger list, select the "Confirmation page", or create one if it doesn't exist.

    • Select the "+" on the top right,
    • Select "Choose a trigger type to begin setup..."
    • Pick "Window Loaded"
    • You don't want this to be trigger on every pages, so choose "Some Window Loaded Events"
    • Add a condition to match only the confirmation page — for instance, "Page URL" contains "checkout/confirmation"
    • Save and name your trigger "Confirmation page"

Tealium

The Tealium extension will automatically fire the Contentsquare transaction code as soon as the transaction values defined have been populated in your utag datalayer.

Adobe Launch

  1. Within Tag properties, select Rules > Add Rule.

  2. Specify a name, events, and conditions.

  3. Add an Action with the following settings:

    • Extension: Contentsquare,
    • Action Type: Ecommerce Trasactions,
    • Name: Contentsquare - Ecommerce Transactions.

  4. On the right-hand side, enter:

    • The transaction ID
    • The revenue
    • The currency

  5. Select Keep Changes > Save.

Event Configuration

The E-commerce tag needs to be fired once on the confirmation page, after a transaction has been made and needs to be tracked. In order to do so, specify the path or the event to be used as a trigger. For example, if you want to target the confirmation page, you could use a similar condition:

If you have chosen the event+condition route, your setup should look similar to this:

Action Configuration

Select the Ecommerce Tag Installation action from the Contentsquare extension

You will then be prompted to fill in the required information by using either strings or Data Elements.

Given the dynamic nature of transaction details, it is required to have previously setup Data Elements with the requested information.

Commanders Act

  1. Add a new tag to your container by choosing the Contentsquare (Builder).

  2. Set the right Contentsquare template selecting Ecommerce.

  3. Fill in all required fields with your Commanders Act variables.

  4. (Optional) If your transactions have different currencies, send Contentsquare the currency value.

  5. (Optional) If you are CS Merchandising customer, add items.

  6. Select a trigger/perimeter that fires only on the confirmation page, and click Save.

Your Tag is ready to be deployed.

Shopify

  1. Click Settings.

  2. In the overlay that appears select Checkout and accounts.

  3. Scroll down to the Order status page section.

  4. In the Additional scripts field, insert the same code snippet that you inserted in the theme.liquid file:

    This is an example of the code including the Liquid Objects pre-defined. You can change these values if need be:

    window._uxa = window._uxa || [];
window._uxa.push(['ec:transaction:create', {
    'id': {{checkout.order_id}},
    'revenue': {{checkout.subtotal_price}}, 
    'currency':{{currency.iso_code}}
}]);
window._uxa.push(['ec:transaction:send']);

    You may already have the Contentsquare Main Tag and other code in the field above: add this new code to the Contentsquare section.

  5. Click Save.

Custom HTML

First, assign a variable to the mandatory fields:

<script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['ec:transaction:create', {
        'id': '{{YOUR ID HERE}}',
        'revenue': '{{YOUR REVENUE HERE}}', 
        'currency':'{{CURRENCY ISO CODE HERE}}'
    }]);
</script>

Then execute the following function to send the above information to Contentsquare:

<script type="text/javascript">
    window._uxa.push(['ec:transaction:send']);
</script>

You can also put it all together in a single snippet:

<script type="text/javascript">
    window._uxa = window._uxa || [];
    window._uxa.push(['ec:transaction:create', {
        'id': '{{YOUR ID HERE}}', 
        'revenue': '{{YOUR REVENUE HERE}}', 
        'currency':'{{CURRENCY ISO CODE HERE}}'
    }]);
    window._uxa.push(['ec:transaction:send']);
</script>

Testing your implementation

Make sure that data is sent correctly to our server with the following steps:

  1. Download our Chrome Extension Contentsquare Tracking Setup Assistant.

  2. Browse your website and, looking at the extension, make sure that:

    • A pageview is sent on every page, or major UI change,
    • You are sending the desired custom vars,
    • If needed, a transaction is sent.

Otherwise, look at our Troubleshooting section.

Wrapping it up

Data is collected

Once all the tags above have been implemented, the site will be fully passing data to Contentsquare and ready for analysis.

You will see the collected data on the solution 3 hours after it has been received.

Going further

To further enrich analysis, refer to our technical documentation and your dedicated Implementation Manager and Customer Success Manager. This will allow for an expanded implementation setup, custom events tracking and Personal Data masking for Session Replay.

Connecting with Third Parties

You can easily connect the Contentsquare solution to 3rd party analytics tools and AB testing platforms.

  • ABTasty
  • Adobe Analytics
  • Adobe Test and Target
  • Google Analytics 360
  • Google Optimize
  • Dynamic Yield
  • Kameleoon
  • Maxymiser
  • Monetate
  • Optimizely
  • Qubit
  • Usabilla
  • VWO

Read the dedicated documentation...

Troubleshooting

My data is not being sent

Using our the Chrome Extension Contentsquare Tracking Setup Assistant, use the checklist below.

  • Is the main tag loaded? (Marker "1" above). If not:
    • Make sure the call is done by your TMS or in your template.
    • Make sure that no Cross-origin Resource Sharing (CORS) rules is preventing the call to be made.
  • Is the tag active? (Marker "2" above, the "Status" should be "active". — Otherwise, contact us)
  • Is the domain authorized? (The current domain should be listed here, on marker "2" above — Otherwise, contact us.)
  • Is the current session tracked? (Marker "3" — Otherwise, update this dropdown menu.)

My CS metric is different from other Analytics tool

The current web analysis technology is dependent on different browsers, operating systems and screen resolution. These different components can affect the quality of the data of all analytical tools.

When you compare Contentsquare data with other analytical tools, you can see differences between major metrics. There are several factors to consider depending on the tool and the indicators you are comparing.

Other analysis definitions. — The following measurement definitions have been extracted from the official Adobe Analytics and Google Analytics documentation. For additional troubleshooting assistance, refer to the corresponding tabs.

Sessions vs Visits metrics

Definitions
[tab] Contentsquare

The number of unique visits that happened within the selected analysis context.

A visit ends after 30 minutes of inactivity.

[tab] Google Analytics

Total number of Sessions (not unique) within the date range.

A session is the period time a user is actively engaged with your website, app, etc.

All usage data (Screen Views, Events, Ecommerce, etc.) is associated with a session.

[tab] Adobe Analytics

A sequence of page views in a sitting. The visits metric is commonly used in reports that display the number of user sessions within the selected time period.

The visit metric is always associated with a time period, so you know whether to count a new visit if the same visitor returns to your site. A session starts when the user first arrives on your site, and ends under one of the following scenarios:

  • 30 minutes of inactivity: Almost all sessions end in this manner. If more than 30 minutes has lapsed between image requests, a new visit begins.
  • 12 hours of consistent activity: If a user fires images requests without a 30+ minute gap for 12 hours, a new visit automatically starts.
  • 2500 hits: If a user generates a large number of hits without starting a new session, a new visit is counted after 2500 image requests.
  • 100 hits in 100 seconds: If a visit consists of more than 100 hits that occur in fewer than 100 seconds, the visit automatically ends. This behavior typically indicates bot activity, and this limitation is enforced to prevent these processing-intensive visits from increasing latency and increasing the time it takes to generate reports.

A visit does not necessarily coincide with a browser session.

Troubleshooting suggestions

A major discrepancy in the visits/sessions can be due to multiple factors:

  • Different metric definition, as per the information shared above
  • The Tag firing method, which might come in place too late, hence allowing the users to bounce before tracking their visit.
  • The trigger chosen might not be the same used for your other analytics tool, hence creating a major difference.

Bounce and Bounce rate metrics

Definitions
[tab] Contentsquare

The ratio between the visitors who entered the site and left it without having seen a second page and all visitors, regardless of the amount of actions taken on that single page.

[tab] Google Analytics

A bounce is a single-page session on your site. Bounce rate is single-page sessions divided by all sessions, or the percentage of all sessions on your site in which users viewed only a single page and triggered only a single request to the Analytics server. These single-page sessions have a session duration of 0 seconds since there are no subsequent hits after the first one that would let Analytics calculate the length of the session.

[tab] Adobe Analytics

Bounces

A visit that consists of a single server call.

For example, a single page visit is a bounce if a visitor does not interact with the page in a way that sends data to Adobe, such as clicking a link or a video start.

Bounce Rate

Shows the percentage of visits that contain a single hit.

Bounce rate uses the Bounces metric and is calculated as: Bounces divided by Entries.

Bounce Rate does not include visits where multiple actions occurred on a single page.

Troubleshooting suggestion

When facing a major discrepancy with bounce and bounce rate, note that the Contentsquare definition of bounce rate takes into account visitors who viewed only a single page, regardless of the amount of events/actions they took.

Pageviews metrics

Definitions
[tab] Contentsquare

Total number of pages viewed.

This takes into account all the artificial pageviews triggered by the trackpageview function.

[tab] Google Analytics

Pageviews is the total number of pages viewed.

Repeated views of a single page are counted.

[tab] Adobe Analytics

A Page View is counted for each server call that is sent.

This metric represents total instances of Page View.

TrackLink calls are not counted as page views and do not increment the Page Views metric.

Troubleshooting suggestions

A major discrepancy in the pageviews count can be due to multiple factors, such as:

  • The events that you're currently tracking with your other analytics tool might not be accounted for as Pageview.
  • If most of your site is running on a SPA framework, note that Contentsquare tracks each re-routing as a new pageview.

Transactions vs Conversions metrics

Definitions
[tab] Contentsquare

The number of sessions during which visitors completed an Ecommerce transaction.

An E-commerce transaction is defined by firing the Contentsquare E-commerce tag.

[tab] Google Analytics

Transactions is the total number of completed purchases on your site.

[tab] Adobe Analytics

Conversions

Custom Conversion reports are based on eVars (conversion variables). Conversion variables can persist beyond the page view and be associated with metrics within its specified expiration. The reports' default metrics are revenue.

All standard eCommerce metrics can be used: Revenue, Orders, Units, Carts, Cart Views, Checkouts, Cart Additions, Cart Removals.

For further reference: https://experienceleague.adobe.com/docs/analytics/technotes/ga-to-aa/reports/conversions-reports.html?lang=en

Orders

The number of orders made on your website during the selected time period.

Troubleshooting suggestions

When facing major discrepancies with the transactions count, if you have different confirmation pages, make sure to fire our ecommerce tag on all of them.

Conversion rate

Definitions
[tab] Contentsquare

The number of sessions with Ecommerce transactions divided by the total number of sessions throughout the selected period.

[tab] Google Analytics

The percentage of sessions that resulted in an e-commerce transaction.

[tab] Adobe Analytics

See the conversions point above.

Troubleshooting suggestions

When comparing conversion rate between different tools, do note that the Contentsquare conversion rate is based on the ratio between the number of visits with a transaction and the total number of visits.

This definition might differ depending on the other analytics tool you're using.

Revenue metrics

Definitions
[tab] Contentsquare

Total purchase amount of all sessions.

[tab] Google Analytics

The total revenue from web ecommerce or in-app transactions.

Depending on your implementation, this can include tax and shipping.

[tab] Adobe Analytics

Revenue is captured on the purchase event, and is defined as the total dollar amount for the sum of the order for each product.

This value comes from the purchase event.

Troubleshooting suggestions

A major discrepancy in the revenue can be due to multiple factors:

  • Contentsquare only takes into account the amount set as 'revenue' in the e-commerce tag when calculating the total revenue displayed
  • If you need to exclude shipping and taxes from the total revenue, you would need to do so before sending the transaction.
  • If you have a returns policy, do note that Contentsquare does not currently support negative values in the transactions, so this won't be tracked.