Monitoring via Page Scenarios

This guide walks you through configuring DataLayer Guard in the Code-Cube.io portal so it can validate your dataLayer events using page scenarios: automated browser flows that replicate real user journeys. New to DataLayer Guard? Start with DataLayer Guard introduction.

What will you do?

• Configure your general DataLayer Guard settings
• Create a scenario and define its starting point
• Add steps that simulate the user journey (cookies, login, navigation, clicks)
• Define the dataLayer templates to validate
• Test, activate, and verify the scenario

⏰ Estimated time: 15 - 20 minutes per scenario

🔧 Requirements: Access to the Code-Cube.io portal with DataLayer Guard enabled, and a list of the pages and user flows you want to monitor

• Step 1 – Configure general settings
• Step 2 – Create a page scenario
• Step 3 – Configure cookie acceptance and login (optional)
• 3.1 Cookie acceptance
• 3.2 Login
• Step 4 – Add scenario steps
• Step 5 – Define the dataLayer template for each collect step
• Step 6 – Test, activate, and verify
• 6.1 Test
• 6.2 Activate
• 6.3 Verify
• Troubleshooting
• Next steps

Step 1 – Configure general settings

Before building any scenario, tell DataLayer Guard which domains to monitor, which time zone to report in, and how often to run.

1. In the portal, go to Configuration > DataLayer Guard

2. Open the General settings panel

3. Fill in the following:
• Company domains: every domain DataLayer Guard should monitor (e.g. example.com, shop.example.com)
• Time zone: the time zone used for scheduled runs and reporting
• Check frequency: how often DataLayer Guard runs your scenarios
4. Click Save changes

⚠️ Important: Add every domain you plan to use as a starting URL in your scenarios. Scenarios that start on a domain not listed here are blocked.

💡 Tip: You can paste a full URL (e.g. https://www.example.com/). The portal automatically strips https://, www., and trailing slashes.

Step 2 – Create a page scenario

A page scenario is one user journey you want DataLayer Guard to replicate. Start with a single, well-defined flow (e.g. "Homepage → product → add to cart") before building broader ones.

1. On the DataLayer Guard configuration page, click Monitoring via page scenarios

2. Click + Add scenario

3. Enter a Scenario name. Use a descriptive label, e.g. Add to cart — running shoes
4. Define the Starting point of the scenario:
• Starting URL: the page where the scenario begins
• Match type: how the URL is matched
• Page type: which part of the URL the match applies to

🧠 Insight: The starting point determines where the headless browser begins the scenario. Keep it as stable as possible: prefer a hostname or short path over a long URL with a query string.

Step 3 – Configure cookie acceptance and login (optional)

Most websites show a cookie banner before the user can reach the dataLayer events you care about. Configure these blocks once per scenario so the rest of your steps run on a clean session.

3.1 Cookie acceptance

1. Inside the scenario, turn Cookies acceptance on

2. Click Add step and configure the click that dismisses your cookie banner:
• Action type: Click on element
• Element selector: a CSS selector for the "Accept all" button (e.g. #cookie-accept)

3. Add more click steps if your banner needs multiple interactions

3.2 Login

1. Turn Login required on
2. Add the steps in order, for example:
• Go to page: the login page URL
• Fill input field: username selector and value
• Fill input field: password selector and value
• Click on element: submit button selector

⚠️ Important: Use a dedicated test account for login scenarios. Never enter real user credentials, because scenarios are stored in the portal configuration.

💡 Tip: If several scenarios share the same cookie or login flow, build it once as a Reusable components and reference it from each scenario.

Step 4 – Add scenario steps

Steps describe the user journey. DataLayer Guard runs them in order. Use collect steps to tell DataLayer Guard which dataLayer events to capture and validate.

1. Inside the scenario, scroll to Steps

2. Click + Add step and choose an Action type for each step

Settings per step:

• Delay: seconds to wait after the step completes (for animations or content that loads later)
• Optional: when on, a failure of this step does not stop the scenario
• Wait for page load: pauses after the action until the new page has loaded
• Opens new page: continues in the new tab or page opened by the action

Example: "Add to cart" flow

1. Go to page → https://www.example.com/
2. Click on element → selector for the product link
3. Wait until element appear → selector for the "Add to cart" button
4. Click on element → selector for the "Add to cart" button
5. Collect dataLayer object → event name: add_to_cart

🧠 Insight: Use Collect dataLayer before navigation when the page navigates away right after pushing an event (e.g. purchase on order completion). The regular Collect dataLayer object only sees events that stay on the current page.

💡 Tip: If a step fails now and then, add a Wait until element appear step before it, or increase the Delay on the previous step.

Step 5 – Define the dataLayer template for each collect step

For every Collect dataLayer object or Collect dataLayer before navigation step, you define what the event should look like: which keys must be present, and what type of value each key holds.

1. In the step row, click the Edit dataLayer template icon

2. The DataLayer Template panel opens on the right

3. For each property, set:
• Key: the dataLayer key (e.g. event, ecommerce.value)
• Type: string, number, boolean, array, or object
• Required: turn on if the key must always be present
• Exact match: turn on if the value must equal a specific value (otherwise only the type is validated)
4. For ecommerce events, click Insert default template and pick a GA4 preset (add_to_cart, begin_checkout, view_item, view_item_list, view_cart, remove_from_cart) to prefill the structure

5. Click Save to close the panel

💡 Tip: Start with the default GA4 template and remove what your site doesn't use. It's faster than building from scratch and avoids typos.

⚠️ Important: Only mark a field as Required if it is present every time the event fires. Marking optional fields as required causes false alerts.

Step 6 – Test, activate, and verify

New scenarios start paused. Activate a scenario only when you're confident its steps are correct.

6.1 Test

Run the scenario in the Scenario Tester to watch every step live and fix any failing step before you activate it.

6.2 Activate

1. In the scenarios table, click the ▶ Play icon next to your scenario, or set Status to Active in the scenario panel

2. Click Save changes at the top of the panel

6.3 Verify

1. Open DataLayer Guard > Dashboard
2. Wait until the next scheduled run (see Check frequency in General settings)
3. Confirm the scenario shows the events you defined under Monitored events
4. Open the run details and check that each event was collected and validated as expected

Troubleshooting

Still stuck? Email support@code-cube.io.

Next steps

• Reusable components: build shared steps, such as cookie or login flows, once
• Scenario Tester: test your scenarios live before they go live
• Notifications & alerts: choose where and how you receive alerts