Snippets rely on triggers to define when and where you want your snippet to run.
This article should be used alongside the Contentsquare Tag Configurator article, which includes details on prerequisites, Snippet creation, and Template selection.
About trigger conditions
Trigger conditions are designed to help you refine where (what pages, under what conditions etc.) a specific snippet will be executed. Conditions are evaluated when the CSTC starts and each time it restarts. If the condition is false
the trigger won’t fire.
Example
Define your snippet to fire only on pages whose URL contains "checkout" or only if an element with the #promotion-banner
ID attribute exists on the page.
Using custom triggers
Once you’ve selected your trigger during Snippet creation, you have two options under "Trigger fires when":
- All pages
- Custom
To configure your custom conditions:
1. Choose a variable:
- URL: property
- Cookie: name
- Window: object chain
- Element: CSS selector
2. Select an operator:
- contains (includes)
- notContains (does not include)
- equals (===)
- notEquals (!==)
- matches (match): RegExp in format /regex/ (optional flags g, i, m and y)
- notMatches: RegExp in format /regex/ (optional flags g, i, m and y)
- startsWith (startsWith)
3. Enter a value.
4. Optionally, click "Add condition" to add multiple conditions, combined with an AND logical operator.
Triggers
Once you create a Snippet and choose a template, you will have a selection of triggers available (depending on the template chosen). Below is the full list of available triggers, how they work and which templates you can find them on.
Element Becomes Visible
This trigger allows the execution of a template when an element is either visible on page load or becomes visible while browsing your pages.
Available for the following templates
- Artificial Pageview
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s whose visibility you would like to detect and the frequency with which you would like to do so.
How it works
The trigger uses the IntersectionObserver API to detect when elements become visible in the viewport (your browser window). This can be as a result of scrolling the element into view, the element appearing as a pop-up, or being selected from among overlapping elements (like tabbed content on a page).
- The trigger is executed on page load when the Contentsquare tag first loads, and checks whether the element in question is present. If found, it begins observing the element/s to detect if they become visible.
- The trigger will NOT fire if the element/s in question is/are already visible when the page first loads. These will be ignored.
- The trigger is subscribed to MutationObserver so it also detects the visibility of newly added nodes that match the selector/s.
- The trigger has 2 settings to specify whether the trigger should fire once or multiple times on a given “natural” page load (when a new page is requested from the server):
- Trigger every time an element that matches the selector becomes visible in the viewport
- If you wish to trigger for multiple elements on a given page, or if the page in question is a single page application (SPA), it is recommended to select this setting.
- Trigger at most once per pageview when an element that matches the selector becomes visible in the viewport.
- Trigger every time an element that matches the selector becomes visible in the viewport
Limitations
- Element Becomes Visible does not check the visibility of nested elements (children and descendant elements).
- Elements made visible through the
background-color
CSS property are not considered visible: If an element has invisible text but a visible background, it is treated as invisible.
Element Exists
This trigger allows for the execution of a template if a given element exists on a page when the Contentsquare tag executes on your pages.
Available for the following templates
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s whose presence you want to detect.
How it works
- The trigger is executed when the Contentsquare tag loads during page load.
- The trigger checks for the presence of specified element/s using the
document.querySelector()
method. - The
${element}
variable referencing the target element is accessible from the Interpolation feature.- For example, you could grab its text by using
${element.textContent}
in the value field of some snippets (Page Event, Dynamic Variable and so on).
- For example, you could grab its text by using
Element Insertion
This trigger allows for the execution of a template when an element is inserted into the DOM after the Contentsquare tag was loaded on your pages (after initial page load). It relies on the MutationObserver interface to detect these changes.
Available for the following templates
- Artificial Pageview
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s whose addition/insertion you want to detect and the frequency with which you want to do so.
How it works
- The trigger is subscribed to MutationObserver and checks whether the inserted nodes match the selector provided.
- Unlike the Element Exists trigger, this one will not trigger for pre-existing elements on the page (at the time when the Contentsquare tag first runs during page load).
- The trigger has 2 settings to specify whether the trigger should fire once or multiple times on a given “natural” page load (when a new page is requested from the server):
- Once per pageview
- Every time the element is inserted in a pageview
- If you would like to trigger for multiple elements on a given page, or if the page in question is a single page application (SPA), it is recommended to select this setting.
- The
${element}
variable referencing the target element is accessible from the Interpolation feature.- For example, you could grab its text by using
${element.textContent}
in thevalue
field of some snippets (Page Event, Dynamic Variable and so on).
- For example, you could grab its text by using
Element Removed
This trigger allows for the execution of a template when an element is removed from the DOM after the Contentsquare tag was loaded on your pages (after initial page load). It relies on the MutationObserver interface to detect these changes.
Available for the following templates
- Artificial Pageview
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s whose removal you want to detect.
How it works
- The trigger is subscribed to MutationObserver and checks whether the removed nodes match the selector provided.
- The
${element}
variable referencing the target element is accessible from the Interpolation feature.- For example, you could grab its text by using
${element.textContent}
in the value field of some snippets (Page Event, Dynamic Variable and so on).
- For example, you could grab its text by using
Element Click or Tap
This trigger allows for the execution of a template based on a click or tap on the specified element/s.
Available for the following templates
- Artificial Pageview
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s you want to detect clicks or taps on.
How it works
- The trigger relies on the Click Event.
- The
${element}
variable referencing the target element is accessible from the Interpolation feature.- For example, you could grab its text by using
${element.textContent}
in the value field of some snippets (Page Event, Dynamic Variable and so on).
- For example, you could grab its text by using
Before Pageview
This trigger allows for the execution of a template immediately before a new Contentsquare pageview is fired.
Available for the following templates
- Custom Variable
- Dynamic Variable
- Element Masking
- Element Unmasking
- Network Requests - Mask URLs
- Page Event
How to use it
Configuration
Contentsquare distinguishes between 2 kinds of Pageviews and this snippet allows you to select if you want it to run on either of them or both, depending on the use case:
- Natural - when a page is loaded “from scratch” after a GET/POST request and response from the server. This is how most websites are built. Typically, the Contentsquare tag is injected on every page you want tracked and fires the pageview when it’s loaded and rendered.
- Artificial - designed to “break down / split” visitor journeys on Single Page Applications (entire websites or specific visitor flows) into individual pages/steps. Can also be used to designate modal pop-ups or any other user experience as a distinct step for more granular Journey Analysis and reporting.
How it works
- It is triggered immediately before a new Pageview is sent to Contentsquare.
- This trigger is particularly useful for Custom Variables that have to be set before the next pageview fires in order to be correctly associated with it.
- It is also the only trigger available for all masking/unmasking templates because they too need to be set up before the initial “Natural” pageview.
Trigger conditions guidelines
When used for masking purposes, you should always set this trigger to fire on "All Pages" to ensure that the masking CSS selectors are set before the main CS tag loads. "Custom" trigger conditions can be used for non-masking templates, like Custom Variables.
Form Submit
This trigger allows the execution of a template based on when a form is being submitted.
Available for the following templates
- Artificial Pageview
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using a CSS selector to reference the <form> element whose submissions you wish to detect.
How it works
The trigger is listening for the submit event fired when a <form> is submitted.
After Pageview
This trigger allows for the execution of a template immediately after a new Contentsquare pageview of any kind is fired.
Available for the following templates
- Dynamic Variable
- Page Event
How it works
Contentsquare distinguishes between 3 types of page views:
- Natural Pageview - when a page is loaded “from scratch” after a GET/POST request and response from the server. This is how most websites are built. Typically, the Contentsquare tag is injected on every page you want tracked and fires the pageview when it’s loaded and rendered.
- Artificial Pageview - designed to “break down / split” visitor journeys on Single Page Applications (entire websites or specific visitor flows) into individual pages/steps. Can also be used to designate modal pop-ups or any other user experience as a distinct step for more granular Journey Analysis and reporting.
- Renewal Pageview - when a session ends after over 30 minutes of idle time on a page/tab, but is then restarted when the page is interacted with again. A new visitor session is created with a new pageview dispatched with this type.
Hash Change
This trigger allows for the execution of a template when the URL Fragment – the part of the URL after the # character – changes.
Available for the following templates
- Artificial Pageview
- Dynamic Variable
- Page Event
History Change
This trigger allows for the execution of a template when the URL changes through a history object change.
Available for the following templates
- Artificial Pageview
- Dynamic Variable
- Page Event
How to use it
Configuration
- The trigger allows selecting which history changes combinations you want the snippet to trigger on:
- pushState - a method to change URLs within single page applications while retaining the previous URL for backward navigation.
- replaceState - a method to change URLs within single page applications while overwriting the previous URL to prevent backward navigation.
- popstate - an event fired when using the browser's back button.
- hashchange - an event fired when the fragment identifier of the URL changes.
- Additionally, you can define a debounce window (up to 400ms) to prevent multiple triggering in cases when multiple history changes occur in rapid succession. A debounced History Change Trigger will only consider the last event and skip the first ones which means that a debounced event will fire up to 400ms after the event actually takes place.
How it works
Before triggering, it checks whether the new URL you’re moving to is different to the one you’re moving from and will only fire if the new and previous URLs are not the same.
Select listeners
- The recommended combination when used for Artificial Pageviews on Single Page Websites (or their sections) with URL changes is pushState + popstate.
- Including replaceState may result in unwanted triggers, causing additional Artificial pageviews to fire.
Mouseover
This trigger allows for the execution of a template when the visitor hovers the mouse over the specified element/s.
Available for the following templates
- Artificial Pageview
- Custom Error
- Dynamic Variable
- Page Event
How to use it
Configuration
The trigger is defined using one or more comma-separated CSS selectors to reference the element/s you want to detect hovers on.
How it works
- The trigger relies on the
mouseover event
. - We also use
element.closest
method to check if the hovered element is nested inside the selected element to prevent it from triggering multiple times on a single hover.