The Contentsquare Tag Configurator (CSTC) is a tool for managing your Tag-related features, providing you with customizable code Snippets, so you can tailor tracking to suit your needs.
You, or your team involved in the Contentsquare implementation, will typically use the CSTC during the initial implementation and thereafter to make updates as your business needs evolve.
Use cases
- Personal data masking: selectively mask and un-mask certain page elements in Session Replay to improve your replay experience, by ensuring you only mask what’s necessary.
- Artificial pageviews: send and track additional “pageviews” in cases where a user’s interaction with a page doesn’t register it as another unique pageview (e.g. pop-up, SPA etc).
- Custom errors: collect errors experienced by your visitors, such as form validation messages or unavailable product warnings (with up to 5 key/value pairs to categorize the errors).
- Custom variable (CVAR): collect additional information on the page, the user, or the session, sent within pageviews
- Dynamic variable (DVAR): collect additional session-level information that can be used for segmentation.
- Page event: collect additional session-level information that can be used for segmentation.
- Network requests - Mask URLs: register patterns to mask URLs collected for API errors and network details.
You'll find specific templates listed and linked below, available for each of the use cases.
Good to know
CSTC ownership
You should identify the appropriate team member/s to update and manage the CSTC, as technical knowledge is required. Note, the CSTC can only be accessed and managed by users with Console Admin permissions.
CSTC and other third-party Tag managers
It’s important to review and keep track of your configurations when using multiple tagging platforms to avoid conflicts.
SRI and self-hosted Contentsquare projects
After making changes on CSTC snippets and publishing, you will need to:
-
SRI: generate a new snapshot manually
-
Self-hosting: retrieve the new Tag
How it works
Snippets, templates and triggers
The CSTC uses Snippets which execute a Tag Command. You create and configure individual Snippets using two components: a template and a Trigger.
-
Step 1 - Create a Snippet: Executes Tag Command
- Step 2 - Select and configure template: The action that will be performed
- Step 3 - Select and configure a trigger: The event that will execute the action
See the list of templates
Once you create a Snippet, the following templates are available to choose from:
Use case: Data masking
- Element Masking: selectively mask targeted elements, such as sensitive, personal or other specific data, while leaving other elements unmasked
- Element Unmasking: selectively unmask targeted elements, or sections of a page, while leaving other elements masked.
- Network requests - Mask URLs (requires Experience Monitoring): register patterns to mask URLs collected for API errors and network details.
Use case: Collect Artificial Pageviews
- Artificial Pageview: track additional “pageviews” in cases where a user’s interaction with a page doesn’t register it as a separate unique pageview.
Use case: Custom event collection
- Custom Variable: collect additional information on the page, user, or session sent within pageviews
- Dynamic Variable: collect additional information on the session that can be used to segment
- Page Event: a visitor interaction to then be used as a filter to segment within Contentsquare
Use case: Error Analysis
- Custom Error (requires Experience Monitoring): collect error messages present in the browsed web page (visible to the user or not)
See the list of triggers
Depending on the template you select, one or more of the following Triggers are available:
- Before Pageview
- Form Submit
- Element Click or Tap
- History Change
- After Pageview
- Element Exists
- Hash Change
- Element Becomes Visible
- Element Removed
- Mouseover
- Element Insertion
Review the full list of triggers, how to use each one and the templates they are available on.
Syntax usage: CSS selector inputs, interpolation, and iterable context
You can use the following guidance to help configure the input fields available for different templates and triggers.
CSS selector inputs
In some templates of CSTC, such as Element Masking, we make use of CSS selectors to target specific elements.
Snippets that rely on CSS selectors (including in their triggers) support a syntax similar to your browser when using the document.querySelectorAll method.
CSS selectors usage
Syntax
You can use the commonly used syntax for CSS, separated by commas:
.classname,#indexname,div[attr=value]
Using dynamic content with interpolation
In order to leverage both plain texts to send as values, as well as dynamic content retrieved from a dataLayer (for example), CSTC leverages a mechanism called interpolation.
Interpolation usage
Interpolation allows you to specify a variable to be used in one of the inputs of the page configuration.
Template availability
Syntax
Interpolation syntax: ${javascriptHere}
The content inside the curly braces will be treated as Javascript variables.
Guidelines
Note that function calls are not supported, except those listed in the ‘Exceptions’ below.
To use interpolation, you must base the Javascript variables on specific root variables, including:
- Window
- Document
- Location
- cookies: Key-Value map of accessible cookies and their corresponding value
You can use interpolation within templates and triggers inputs, making it possible to concatenate interpolation with common text, or interpolate multiple variables within the same input.
If the interpolated values are undefined, the template execution will be aborted.
Examples
Valid ✅ | Invalid ❌ |
${window.dataLayer[0].pageName} | ${dataLayer[0].pageName} |
${location.href.pathname} | ${document.querySelectorAll("#selector")[0].textContent} |
We are located here: ${location.href.pathname} |
|
${cookies._cs_id}${cookies._cs_s} | |
${cookies._cs_id} |
Exceptions
Even though interpolation does not intend to allow function calls, some functions can be used within the interpolation feature:
-
window.location.hash.replace()
- Allows to replace the # character on the Artificial Pageview template
-
window.sessionStorage.getItem()
- Allowed for historical reasons
-
document.querySelector("<valid-css-selector>").textContent
-
document.querySelector("<valid-css-selector>").value
-
new Date().getTime()
Iterable context
It allows fetching values from arrays, such as Javascript variables. Iterable context is to be used when the position of the value you want to retrieve from an array is not known.
It can help you filter values from an array to extract the useful payload and then use them on your templates.
Iterable context usage
Iterable context can help you filter values from an array to extract the useful payload and then use them on your templates.
Availability
Iterable context can be used on the following templates:
Syntax
The iterable context input field requires a specific syntax to achieve this purpose:
values(<object or array>)[?<fieldName>] [| [<min>:<max>]]
Specifically, the syntax is a subset of JMesPath Expressions.
Syntax details and description:
MANDATORY values(<object or array>) |
Defines the Object or Array you want to iterate on. |
MANDATORY [?<fieldName>] |
Filter: Iterates on values and selects only the one(s) that meet the filter expression |
OPTIONAL [<min>:<max>] |
Defines a range of indexes to be iterated on. |
This syntax allows extracting values that match a specific filter, whose outcome will be an array of values.
The main purpose of the iterable context is to allow us to use the result of the evaluation above. The template will be executed as many times as the number of items in our filtered subset.
Important to note
<object or array> is referenced from the interpolation context. For each execution, the interpolation context will be injected with a “$" variable that resolves to the value being iterated on.
Example: Page Event template
Assuming a PageEvent template is being created with the following input:
Iterable Context |
values(window.example)[?key] | [1:2]
|
EventName
|
Value: ${$.value}
|
values(window.example)
|
[ |
[?key]
|
[ |
[1:2]
|
[ |
The Page Event template will be executed only once, and $.value will be interpolated to 3.
Example: Google Tag Manager (GTM) DataLayer
In this instance, we want to capture the value window.dataLayer[i].google_tag_params.make found inside a GTM DataLayer (which is an array of objects).
This is a classic example where we can retrieve the data we are looking for using Iterable Context.
The dataLayer is an array of objects, each containing different data points and information.
Upon closer look, the items at indexes 11 and 12 seem to own a google_tag_params field.
Step 1: The first step is to filter the dataLayer for only the objects that contain the google_tag_params keys, which is done using the following expression
values(window.dataLayer)[?google_tag_params]
___
Step 2: After the filtering is applied, 2 objects are returned; However, we are interested in the value of just the second one. Therefore, to further narrow it down to a single object, we would add the | [1:2]
part at the end of our expression.
values(window.dataLayer)[?google_tag_params] | [1:2]
___
Step 3: Eventually, having isolated the object that holds the key/object whose value/property we want to collect, we can access it using the following interpolation syntax (inside the snippet's value field):
${$.google_tag_params.make}
___
As you can see in the example above, the Iterable Context is populated with the proper syntax and the value input text is using interpolation to collect the value made available by the Iterable Context.
How to create, manage and deploy Snippets
First, you must navigate to Tag Configurator by clicking your profile icon (in the top right), followed by 'Tag Configurator'.
The workflow for creating and managing Snippets in the CSTC is as follows:
Step 1: Create (or edit) a Snippet
1. Select ‘+ New snippet’.
2. Give your snippet a name (something descriptive that tells you what it does).
3. Select your chosen template.
4. Select one of the available triggers (triggers differ per template).
5. Click ‘Save’.
Step 2: Deploy your Snippets
To deploy your Snippet/s you will need to publish the new version of the Tag, including all the changes to new or existing Snippets.
1. Check and update the ‘publication status’ of your Snippets as required.
- ‘On’: These will be deployed to the Tag upon publishing. Newly created Snippets are set to ‘On’ by default.
- ‘Off’: These will be disabled from the Tag upon publishing.
2. Click the ‘Publish [x] change(s)’ button. In order to approve and publish your changes, an email will be sent to your registered email address containing a four digit code.
3. On the new window that appears enter the code you received via email to approve the changes.
4. Click ‘Publish all snippets’ and the new Tag will be deployed, including all your Snippets and any changes made.
Step 3: Test your implementation
1. Download the Contentsquare Tracking Setup Assistant Chrome extension.
2. Allow for 5 minutes to pass, clear your browser's cache and open (or reload) the page where your newly created snippet is supposed to fire.
3. Go on your website (or the specific page of your website) where the published snippet is supposed to fire and take the action that your published snippet is supposed to fire on.
4. Click to open the Contentsquare Tracking Setup Assistant extension and check under the last "New pageview sent" section whether your Custom/Dynamic Variable or Page Event was successfully collected.
Note that masking/unmasking snippets should be checked inside the Contentsquare platform itself.
Enable/Disable Snippets
You can enable and disable Snippets by using the toggles under the publication status:
‘On’: to enable a snippet.
‘Off’: to disable a snippet. Use this if you want to temporarily disable a Snippet without completely removing it from the project (that would require deleting a Snippet).
You will always need to publish any changes in order to deploy them to the Tag.
Delete a Snippet
Important: You should take extra caution before deleting any snippets, especially those related to masking, to validate the impact of doing so (such as exposing personal data in the case of masking).
To permanently delete a Snippet and remove it from the CSTC (including your Contentsquare project), click the three-dot menu next to a Snippet and click ‘Delete’. Note, this cannot be undone.
FAQs
Is the CSTC available for Mobile Apps?
The CSTC is currently available for WebViews, as long as the Tag is loaded on Webviews too.
Tag types and custom code: M2P and "Standard"
If you already have some custom code in place, note that CSTC Snippets won’t replace it. Meaning that, for example, if you have configured Artificial Pageviews in your custom code, and you create an Artificial Pageview Snippet in CSTC, you will have duplicated pageviews.
Can I check versioning changes, or undo changes made via the CSTC?
As there is currently no version log, or undo function, you will need to re-configure any Snippets as necessary and then deploy them to the Tag, by publishing your changes again.
What to do if I’ve created an issue on my site, or have concerns of a personal data leak?
You should disable and un-publish the snippet that caused the issue and, in the case of a personal data leak, you should contact our Support team.
Can I use custom Javascipt?
Only allowlisted methods and functions can be used within an interpolation context.