This guide walks you through configuring DataLayer Guard in the Code Cube portal so it can validate your dataLayer events using page scenarios, automated browser flows that replicate real user journeys.

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 event templates to validate
• Activate the scenario and verify it runs correctly

⏰ Estimated time: 15–20 minutes per scenario 🔧 Requirements: Access to the Code Cube portal with DataLayer Guard enabled, and a list of the pages and user flows you want to monitor

🧱 Step 1: Configure General settings

Before building any scenario, set the basics that DataLayer Guard needs to know about your website: which domains it should monitor, what time zone to report in and how often it should 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 should run 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 will be 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 new 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. From the DataLayer Guard configuration page, click Monitoring via page scenarios
2. Click + Add scenario
3. Fill in the 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 should be matched
• Page type: which part of the URL the match applies to

Match-type options:

Page-type options:

🧠 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 query-string URL.

🍪 Step 3: Configure cookie acceptance and login (optional)

Most production 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.

3a. Cookie acceptance

1. Inside the scenario, toggle Cookies acceptance to 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 additional click steps if your banner requires multiple interactions

3b. Login

1. Toggle Login required to On(Optional)
2. Add steps in order, e.g.:
• Go to page the login page URL
• Fill input field username selector + value
• Fill input field password selector + value
• Click on element submit button selector

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

🧩 Step 4: Add scenario steps

The steps section is where you describe the user journey. DataLayer Guard executes each step 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 one

💡 Tip: If multiple scenarios share the same cookie or login flow, build it once as a Reusable component (from the configuration page) and reference it from each scenario.

Available step types:

Per-step settings:

• Delay: seconds to wait after the step completes (use for animations or async loads)
• Optional: when on, a failure of this step does not interrupt the scenario
• Wait for page load: pauses after the action until the new page has loaded
• Opens new page: switches execution to the new tab/page opened by the action

Example step sequence, "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 "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: Collect dataLayer before navigation is the right choice when the page navigates away immediately after pushing an event (e.g. purchase on order completion). The regular Collect dataLayer object only sees events that remain on the current page.

❓ Troubleshooting: If a step fails intermittently, 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 tell DataLayer Guard what the event should look like. The template defines which keys must be present and what type of value each key should hold.

1. In the step row, click the Edit dataLayer template icon
2. The DataLayer Template drawer opens on the right
3. For each property:
• Key: the dataLayer key (e.g. event, ecommerce.value)
• Type: string, number, boolean, array, or object
• Required: toggle on if the key must always be present
• Exact match: toggle 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 from the GA4 presets (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 template drawer

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

⚠️ Important: Only mark a field as Required if it must be present on every firing of the event. Marking optional fields as required will produce false-positive alerts.

🚀 Step 6: Activate and verify

A scenario is created in paused state by default. Activate it only after you're confident the steps are correct.

Activate

1. Save the scenario (the Save changes button at the top of the drawer becomes active when you have unsaved edits)
2. In the scenarios table, click the ▶ Play icon next to your scenario, or toggle Status to Active in the scenario drawer
3. Save changes

Verify

1. Open DataLayer Guard > Dashboard
2. Wait until the next scheduled run (see your 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 table: