How to define required keys

Required keys tell DataLayer Guard which keys must always be present in a dataLayer event. Setting them correctly is the key to useful alerts: too few required keys and you miss real problems, too many and you get false alerts.

You define required keys in the dataLayer template of each collect step in your scenario.

What will you do?

Open the dataLayer template of a collect step
Set the key, type, and required setting for each property
Avoid false alerts from optional keys

⏰ Estimated time: 5 minutes per event

🔧 Requirements: Access to the Code-Cube.io portal and a scenario with at least one collect step. See Monitoring via Page Scenarios

Step 1 – Open the dataLayer template
Step 2 – Set each property
Step 3 – Decide which keys are required
Step 4 – Test your template
Troubleshooting
Related pages

Step 1 – Open the dataLayer template

Open your scenario on the DataLayer Guard configuration page
In the row of a Collect dataLayer object or Collect dataLayer before navigation step, click the Edit dataLayer template icon
The DataLayer Template panel opens on the right

💡

Tip: 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). Then remove what your site doesn't use. It's faster than starting from scratch and avoids typos.

Step 2 – Set each property

For each property in the template, set:

Setting	What it does
Key	The dataLayer key, e.g. `event` or `ecommerce.value`
Type	The expected type of value: `string`, `number`, `boolean`, `array`, or `object`
Required	Turn on if the key must always be present. If it's missing, DataLayer Guard reports an error
Exact match	Turn on if the value must equal a specific value. Otherwise, only the type is checked

Click Save to close the panel.

Step 3 – Decide which keys are required

Ask for each key: is it present every time this event fires?

Yes: mark it as Required. For example, event on every event, or the transaction ID on a purchase event
No, only sometimes: leave Required off. DataLayer Guard still checks its type when the key is present

☝🏼

Important: Marking keys that are only sometimes present as Required causes false alerts. If you see random validation errors on one field, this is usually the cause.

Step 4 – Test your template

Run the scenario in the Scenario Tester. For each failed step, it shows the expected value next to the actual value for every parameter, so you can see right away whether a key is missing or set up incorrectly.

Troubleshooting

Problem	Likely cause	Fix
Random validation errors on one field	The field is marked Required but is only sometimes present	Turn off Required for that field
`Collect dataLayer` step finds no event	The event fires after navigation, or the event name doesn't match	Switch to `Collect dataLayer before navigation`, and check the `event` value

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