Artificial Pageviews (APVs) allow you to send and track additional “pageviews” in cases where a user’s interaction with a page doesn’t register it as a separate unique pageview.
These instructions should be used alongside the Contentsquare Tag Configurator article, which includes details on prerequisites and Snippet creation.
Commonly used when:
- The website - either partially or in full - is built as a Single Page Application (SPA) (common with frameworks like React, Angular etc.)
- An action changes the content displayed on the page without refreshing it or changing its URL (e.g. modal pop-up)
How to use the template
Once you've created your new snippet and selected the Artificial Pageviews template, you can use our guidelines below for recommended and common use cases.
Step 1: Complete template input fields
1. Path: Enter the path argument to be sent to Contentsquare when your Artificial Pageview fires. It can be a fixed string, however, in most cases interpolation is the suggested approach.
2. Current pageview: Set to “True” by default, select “False” instead if you don’t want the path specified to be valid on only the current pageview.
3. DecodeURI: Set to “False” by default, select “True” instead if you want to use DecodeURI on the path before sending the pageview, to convert the URI-formatted path to UTF-8.
Step 2: Select and configure the Trigger
Select from one of the available triggers and define its conditions depending on your needs.
Available Triggers for this template
- Element Becomes Visible
- Element Click or Tap
- Element Insertion
- Element Removal
- Form Submit
- Hash Change
- History Change
- Mouseover
Step 3: Save Snippet
Save the changes to your Snippet configuration and, when ready, follow the steps to deploy it.
Template and trigger guidelines
Single Page Application (SPA) with URL changes
This applies if your entire website (or a specific flow/wizard) is a single page application that uses history changes to modify the URL accordingly when users transition between the different pages/steps.
Recommended Trigger:
-
History Change (except in rare cases when the website uses hash changes (identified when the URL has a hash (#) sign and the part of the URL that changes is after the hash sign)).
- Note, Custom Variables are currently unavailable with the History Change trigger.
- URL Change events: change to popstate, pushState unless already selected by default. This is the recommended setup in 95% of cases.
- Trigger fires when: All pages. Unless there is a specific reason to limit it to specific URLs only, in which case you can use the “Custom” trigger condition.
URL modification
Typically, you will retain the actual new URL without any modification. Therefore, in the Path input field, you will want to use the following syntax (copy-paste and note the curly braces):
${window.location.pathname}${window.location.hash.replace('#', '?__')}
Testing and troubleshooting guidelines
- Check your “happy path”: Follow the “happy path” on your website to ensure the APVs are firing where and as expected.
- Check for “double triggers”: For example, when toggling product variants on Product Description pages, or when moving to a given page such as the Checkout. (Selecting only popstate and pushState can typically mitigate this).
- Unexpected APVs: If you spot any unwarranted APVs getting triggered, this could be caused by a replaceState history change firing alongside the pushState one (on the website). Try modifying the URL change eventslisteners in the History Change trigger to exclude replaceState (from the dropdown) and testing again. This typically resolves it.
- Websites with Checkouts: Confirm how the APVs are triggered as you progress through the shipping, billing and other steps. Do not neglect to check what happens when you edit (go back) to previous filled out steps (i.e. are APVs getting triggered or not and so on…).
- APVs firing multiple times: If you encounter a situation where transitioning between (some) pages causes the APV to fire more than once, and you have ruled out replaceState being responsible, then you could try enabling the “Debouncing” option and adjust the timeout to be any number up to 500 milliseconds.
- Reviewing history changes on your website: If you want to see for yourself what history changes occur on your website, you can execute the following code in the console and look at the console.warn (in yellow) output in the console:
(function(){var oldpushState=window['history']['pushState'];window['history']['pushState']=function(e){console.warn('pushState detected');return oldpushState.apply(this,arguments);};var oldreplaceState=window['history']['replaceState'];window['history']['replaceState']=function(e){console.warn('replaceState detected');return oldreplaceState.apply(this,arguments);}})();
The output will be "pushState detected" or "replaceState detected", or both.
Single Page Application (SPA) without URL changes
If the SPA does not have URL changes when you move between the pages/steps, then simply having APVs is not enough, because you'll still need a way to tell them apart inside the Contentsquare mappings.
Custom Variables (CVAR) alternatives:
- Until CVARs become available soon as part of the APV snippet, we recommend amending the URL that gets passed to us by appending a unique value to the URL.
- This could be manual if this is a relatively limited flow, and you are creating each APV trigger individually based on some unique character of each step/page (for example, a dynamically added HTML element that does not exist on any other page/step).
- For example, you could use this syntax in the Path field (where /step1 will be appended to the end of the actual URL) like this: ${window.location.pathname}/step1
- If the flow in question has something on the page that denotes each step (for example, a breadcrumb widget), you may consider appending its text to the step and making it dynamic using interpolation, for example (where div.step-box.active is the CSS selector that holds the breadcrumb text): ${window.location.pathname}/${document.querySelector("div.step-box.active").textContent}
Recommended Triggers:
While you could theoretically use almost any trigger, typically, in such a situation your best options are the Element Insertion, Element Becomes Visible or Element Removal triggers. The first thing you would want to do is determine how the SPA is built - whether the steps (or at least their top parent containers) are preloaded, if their visibility is toggled as you move between the steps, or whether the content is dynamically generated and destroyed each time you move between the steps.
- If each step is dynamically added/destroyed, then the Element Insertion trigger is probably your best choice.
- If the SPA steps are preloaded, then you will want to use the Element Becomes Visible trigger in a similar fashion.
However, you must keep the following in mind for both triggers:
-
- In order to use the Element Insertion trigger, you must first identify an element on the page that 1) does not exist prior to moving to the step you want to trigger the APV for, 2) gets added to it dynamically as you move to it and 3) does not exist on any other step/page.
- If you configure your Element Insertion trigger to fire multiple times per page view (for each time the element in question is added to the page) watch out for any false positive triggers when testing.
- When testing, make sure to validate the APVs are firing not only when moving up the flow but also back and forth.
- The Element Insertion trigger itself is simple to configure - you just need the CSS selector for the element discussed above and to define where you want it to fire (if the SPA without URL changes is confined to a specific part of the website only, then we recommend using the custom conditions to only fire on that URL instead of the entire website to avoid possible unwanted triggers elsewhere).
- Similar logic applies here as it does for Element Insertion.
- The Element Removal trigger is similar to the Element Added trigger, so all the same things apply. However, typically, you won't need to use this trigger because the Insertion one should be enough.
Fire an APV for modal pop-ups and other one-off use cases
There are 2 items you need to configure:
- Modify the URL to tell it apart from the page it's on
- Use the most suitable trigger
This value could be manual if this is a relatively limited flow, and you are creating each APV trigger individually based on some unique character of each step/page (like a dynamically added HTML element that does not exist on any other page/step). For example, you could use this syntax in the Path field (where /add_to_cart will be appended to the end of the actual URL):
${window.location.pathname}/add_to_cart
Recommended Triggers:
While you could theoretically use almost any trigger, typically, in such a situation your options are limited to the Element Becomes Visible and Element Insertion triggers. (For example, Element Click or Tap is not as reliable because it will still fire even if, in reality, there was a problem on the page and the pop-up didn't work).
To determine which trigger you should use, you can investigate whether the content in question (modal pop-up etc.) exists in the HTML when the page in question first loads or not. This is because, often the element is preloaded but hidden, meaning the Element Insertion trigger isn't going to work. You can achieve this by following these steps:
1. Duplicate your page to a new tab (right-click the tab > duplicate, or any other way)
2. Trigger the content you want to fire the APV on.
3. Look for a unique element inside the newly added content not found anywhere else on the page.
4. Now, check the duplicated tab for that same element (without triggering the modal).
If the element doesn't exist on page load (which means it was added dynamically) you will want to use the Element Insertion trigger. If, on the other hand, the content in question is present in the HTML but is just hidden, you would instead want to use the Element Becomes Visible trigger.
- In order to use the Element Insertion trigger, you would first want to identify an element in the modal that does not exist prior to it being opened.
- The Element Insertion trigger itself is simple to configure - you just need the CSS selector for the element discussed above and define whether you want it to fire everywhere or limit it to specific pages.
- The Element Becomes Visible trigger should be used in case the modal pop-up HTML already exists on the page even before it was triggered for the first time.
- For Element Insertion and Element Becomes Visible triggers, you can choose whether you want them to fire each time the element in question is added to the page, - which means that you'll have an APV for each time the modal is opened (but not closed) - or once per pageview.
- The Element Becomes Visible trigger won't work if the element in question does not exist on page load. It means that rarely you may encounter a situation where the element in question is added to the page after our tag has run. You can contact your CSQ success manager for help in this case.
It's a good idea to also fire an APV when the modal is closed, which is where the Element Removed trigger comes in handy. All the same things apply, and since you're back on the "original" page, you do not have to modify the URL, so the following should be put into the Path:
${window.location.pathname}${window.location.hash.replace('#', '?__')}