Validate your QProtocol setup with the Validation dashboard

In this article...

We'll show you how to use the Validation Dashboard to find, diagnose, and fix issues in your QProtocol setup.

Intro

Validating your setup is a crucial part of setting up Qubit on your site and we highly recommend paying particular attention to our setup guides and the field-level requirements for each event.

As a first step in validating your setup, we recommend using the Qubit Debugger. This tool provides a visualization of the events emitted when each of your pages is rendered and represents a simplified check of event validity event schemas.

Following this, we recommend using the Validation Dashboard for a more comprehensive site-wide validation of your QProtocol setup.

The Validation Dashboard

The Validation Dashboard provides self-service access to your QProtocol setup and enables you to troubleshoot issues with QProtocol events in your setup and based on actual visitor activity on your site.

One of the key benefits of the dashboard is that it allows you to test your data layer against a list of key events and data points; clear explanations are given of any issues so that you can understand and improve your data quality to take full advantage of Qubit's range of custom and programmatic experiences.

TIP: Your data layer can be tested against a range of criteria, starting from Essentials and Best practice, through to those events that are required to drive those specific Qubit products, such as Qubit Aura and Recommendations that you have chosen, including Recommendations and Social proof. See A focus on filters below for more information.

Getting started

To open the dashboard, select Data tools and Validation from the side menu.

Using the dashboard to troubleshoot issues

The dashboard has two principal cards, the QP events panel, which lists the QProtocol events according to your chosen filter, and the Status panel, which provides details of the percentage of valid events and a quality checklist that you can refer to in your quest to guarantee the highest levels of data quality.

Let’s start by looking at the QP events panel.

QP events panel

The QP events panel is populated with the events that correspond to the filter you select in the Status panel. The results are shown for the defined time period, which can be 15 minutes, 1 hour, or 24 hours. In the following example, the user has chosen to troubleshoot all the events emitted in the last 24 hours:

time period

Typically, you would use the 15 minutes option to get the most recent data and check to see if updates are performing as expected as they roll out across your website. The 24 hours options should be used to get a broader picture of how QProtocol event data is being generated by your visitors to your site over a longer period of time.

Let’s take a look at an example of what is shown in the QP events panel. Later on, we will look at how we can deep dive into an event to troubleshoot issues.

So, in the Status panel, we will select the filter Essentials. This filter includes only 2 events, the view event, for example, ecView, egView, or trView and a transaction event, for example, ecBasketTransactionSummary. These 2 events represent the absolute minimum requirements in a QProtocol setup.

For both events, we show a unique count, a validity, expressed as a percentage, and the date and time when the event was last collected by Qubit. In the following example, we see that the ecView event was collected 8,102 times in the last 24 hours and has a validity of 57%.

What does this mean? Essentially, it means that, for reasons that we will cover later on, 43% of the ecView events collected by Qubit were not processed. They were emitted and collected, but not processed.

This is definitely something that should be investigated given the importance of the view events:

ecView

By comparison, ecBasketTransactionSummary was collected 50 times but has 100% validity.

Selecting an event from the panel opens an additional view that explains the purpose of the event and any associated issues. We will look at this in detail in Troubleshooting issues.


A focus on event validity

Why is it important that QP events are valid? Even though valid and invalid are collected and stored in BigQuery, only valid events are processed. Invalid events by comparison are not processed and the data within the event is not available for use in the Qubit platform. Invalid events therefore represent lost data.

Lost data has downstream consequences that can potentially affect segment metrics, reporting against experience goals and the likely impact of an experience, and your wider ability to influence your customers with personalized experiences.

Troubleshooting event validity is therefore a crucial part of setting up Qubit. Beyond using the dashboard to help you in this task, we highly recommend paying particular attention to our setup guides and the field-level requirements for each event.


Status panel

This panel shows the aggregated event validity percentage, access to the filters for your property, and a data quality checklist that you can refer as you work towards great data quality. Let’s take a look.

Following on from the above example, we see that the Status panel reports the overall event validity as 79%. This percentage is derived from the combined percentage validity of the events shows in the QP events panel, divided by the number of events shown.

Our checklist reports that the required QP events for the Essentials filter have been implemented and that both events aren’t missing any recommended fields according to our QProtocol schema.

However given the relatively low validity of the ecView event, we see that the checklist item Required QP events are at least 98% valid has not been fulfilled.

checklist


A focus on filters

Filters enable you to select what you want to validate your QP against. For example, you might wish to validate against the events required for a particular product such as Recommendations or Qubit Aura. To see all QP events in your implementation, select All.

The filters available to you will vary according to vertical and will be based on your Qubit setup. When you select a filter, the QP events panel is updated and will show the QProtocol events associated with that filter.

Refer to the following table, which shows the filters and events included in each filter for the eCommerce vertical as an example:

Filter

Description

Events included

Essentials

The absolute minimum events in a QP setup

View event and transaction event, ecView ecBasketTransactionSummary

Aura

The events required to set up Qubit Aura

ecView, ecProduct, ecBasketItemTransaction, ecBasketTransactionSummary

Best practice

Our recommended events by vertical, for example, see:
Setup for eCommerce
Setup for eGaming

ecBasketSummary, ecView, ecUser, ecBasketItemTransaction, ecBasketItem, ecProduct, ecBasketTransactionSummary, ecBasketItemAction

Recommendations

Our recommended events for the Recommendations Programmatic Experience

ecView, ecProduct, ecBasketTransactionSummary, ecBasketItemAction

Abandonment recovery

Our recommended events for the Abandonment recovery Programmatic Experience

ecView, ecUser, ecProduct, ecBasketTransactionSummary

Social proof

Our recommended events for the Social proof Programmatic Experience

ecView, ecUser, ecProduct, ecBasketTransactionSummary, ecBasketItemTransaction

INFO:In the current release, the filters are restricted to those mentioned in the table above. Additional filters will be added in future releases.


Troubleshooting issues

Finding issues with your setup starts in the QP events panel. Ideally you are looking for 100% event validity, but you should pay particular attention to any event with a large percentage of invalid events, as shown in the example below:

ecProduct

Here we see that ecProduct has a validity of 67%. This means that 33% of the ecProduct events emitted across your website are invalid; as we touched on earlier, the data in these invalid events will not be processed by Qubit for use in the platform. This will have a substantial impact on your ability to correctly understand your visitors' product and product category preferences, possibly leading to incorrect segmentation, metrics, and misleading experience results.

We can start to troubleshoot this issue immediately by selecting the event. This opens an additional view with an explanation of the purpose of the event, the number of issues found over the selected time period, and importantly the issues found. In the following example, we see 747 ecProduct events with data quality issues and 26 with missing information issues, a total of 773 invalid events:

issues

Refer to the following table for an explanation of issue types:

Issue type

Description

Examples

Data quality

Depends on the event, but can include:

-event field containing an invalid value

-event contains required and valid data points but contextual issues have been found that will affect the quality of the generated data

product.productId and product.sku are identical

Corresponding ecBasketSummary event is missing

Corresponding ecBasketItem event is missing

Schema validation

Invalid field type

Invalid field type for entrySuccess field

Expected type is boolean but was string

Missing information

The event contains the required data points but 1 or more of those data points is missing value that is required by one of more of Qubit’s products

product.description is null

basket.quantity is null

Non-critical

The event contains the required data points and valid values but has been customized in a non-standard implementation

Custom properties extended beyond the expected schema

DANGER: Pay particular attention to schema validation issues—events that are found to fail our validation checks are rejected by our gatekeeper. These events are stored in the BigQuery table failed_events and can be used for monitoring and checking but are not available for use in the Qubit platform, with an obvious negative impact on reporting against your experiences.

The next step in troubleshooting issues is to deep dive into the issue itself. You do this by selecting deep dive. This exposes an example of the issue type from an actual QProtocol event emitted by your website.

We can now scroll through the event until we find the issue, which is highlighted. Here we see, as reported above that the value in product.productId matches the value in product.sku and is a good example of a type of issue that the Qubit Debugger would not pick up:

event schema

With this information to hand, it should now be possible to correct the issue in your setup.

Last updated: March 2021
Did you find this article useful?