Keep your zones stable when your site changes

Zoning links each interaction to a page element by identifying the element in your site’s HTML. If 
a site release changes that HTML structure, existing zones may no longer match the same elements and may show zero or unexpected data.

This article explains how to give important page elements a stable identifier so that your zoning data remains consistent when your site changes.

Before you begin

Decide which elements you want to protect. Start with elements that your teams analyze over long periods, such as:

• Fixed homepage blocks
• Menu entries
• Product page buttons whose position can change with stock or content
• Repeated components, such as product tiles

For each important block, consider protecting both the block and its main button. Protecting the block prevents changes outside it from affecting the elements inside it. Protecting the button separately prevents changes inside the block from affecting the button.

Choose identifier values that:

• Use only letters, numbers, hyphens, and underscores
• Are unique on the page
• Stay the same between releases
• Do not include spaces, accents, or dots
• Do not include campaign names or dates

An invalid or duplicate value is ignored. The element’s existing HTML ID is also ignored in this situation.

Available options

Review the options below and use the one that matches your plan, site setup, and implementation requirements.

Option A: Use an attribute or CSS class

Use this option when your site already has an attribute or CSS class that remains stable between releases, such as a product ID or component name.

1. Check that the identifier is stable and unique

Confirm that:

• The attribute or class remains the same
• The value appears only once on the page
• The element does not have a temporary duplicate, such as a mobile and desktop version rendered at the same time

If the same value appears more than once, Contentsquare cannot use it for those elements. It may try a unique CSS class next, followed by the element’s HTML ID, and use the element’s position as a last resort.

2. Open the data collection settings

1. In the Console, open the data collection settings for Zoning, CS Live, and Heatmaps.
2. In Unique attributes, add the attribute name. Enter the name only, not a value. For example, enter data-product-id.
3. In Unique CSS classes, add a class that appears only once per page. Enter the class name without the dot. For example, enter store-locator.

During implementation, your Implementation Manager can help configure this setting. If you identify a post-implementation issue, contact Support or your Technical Account Manager.

This setting applies to the whole site from the day it is saved. Every element whose attribute value or class is unique on the page receives a new name at that point, unless it already has an override ID.

Elements inside a matching element also receive a new name unless they already have their own override ID, unique attribute, or stable HTML ID.

Option B: Add an ID with the Contentsquare Tag Configurator

Use this option to add a stable ID without changing your site code.

Create a snippet

1. In the Console, open the Contentsquare Tag Configurator.
2. Create a new snippet.
3. Name the snippet after the element it protects. For example, Override ID – HP Enchanting Gift.
4. Select the Element ID Override template.

Select the element

In CSS Selector, target exactly one element using a selector that is unlikely to change.

You can target an element using:

• Its link destination, such as a[href*="store-locator"]
• An aria-label
• A data attribute that remains stable between releases

Avoid selectors that use:

• Positions such as :nth-child
• Generated class names
• Values that change between releases

If the selector matches several elements, the snippet applies the attribute only to the first element in DOM order. Contentsquare does not display a warning.

Enter the override ID

In Attribute Value, enter the stable ID value you chose.

Do not leave this field empty. An empty value causes Contentsquare to ignore the element’s HTML ID, which can rename the element and everything inside it.

Use only letters, numbers, hyphens, and underscores. Make sure the value is unique on the page.

Select the trigger

Select Before Pageview as the trigger.

• Enable both:
  Natural pageviews
  Artificial pageviews

Artificial pageviews cover page changes that do not reload the page.
 

Option C: Add an ID in your site code

Use this option when you want the identifier to ship with the component and remain in place through future releases.

Implement the override ID in your site code

1. Add the override ID to the component

Add the data-cs-override-id attribute to the component’s template.

For example:
<section data-cs-override-id="hp-enchanting-gift">

Choose a value that is stable and unique on the page.

2. Give repeated components unique values

For repeated components, build the value from a product or component reference.

For example:
<div data-cs-override-id="plp-tile-VCARA12345">

This works only when each product appears once on the page. If the same product appears more than once, the resulting value is not unique and cannot be used reliably.

3. Reuse existing override IDs when possible

If an element already has an ID assigned by a Tag Configurator snippet, use the same value, and keep the same element type.

This lets your existing zones continue matching without an additional break when the code change goes live. After the release is live, delete the Tag Configurator snippet.
 

Plan for one break in your data

Most changes give the element a new name in Contentsquare from the day the change goes live. Zones created before that change may stop matching.

To limit the impact:

1. Group related identifier changes into the same release.
2. Take new screenshots after the release.
3. Redraw your zones on the new screenshots.
4. Start your analysis periods after the identifier change.

Test the implementation

1. Open the live page.
2. Right-click the element and select Inspect.
3. Check that the element has the expected ID, attribute, or CSS class.
4. In the Elements panel, search the HTML for the value.
5. Confirm that the value appears exactly once.

Test the element in states where duplicates may temporarily appear, such as:

• Cloned carousel slides
• Mobile and desktop menus rendered together
• Modals
• Other temporary page states

In Contentsquare, take a new screenshot and confirm that your zones display data.

Keep the identifier stable after each release

After every site release:

• Confirm that the identifier is still present.
• Confirm that it still appears only once on the page.
• Keep the element type the same. For example, changing a div to a section can cause the zone to stop matching.
• Recheck Tag Configurator snippets. A site change can invalidate the CSS selector without displaying a warning.
• Include the identifier checks in your release testing.

What to read next

• How to create a Zoning
• Troubleshoot Zoning Analysis