Schema extensions

This is for:

Developer

In this article, we’ll look at how you go about requesting an extension to the QProtocol schema.

Intro

QProtocol has a standard set of events and event fields, which can be extended with client-specific events and event fields.

Warning

Without a schema extension any custom events you emit will not be collected by Qubit and will therefore not be available in the Qubit platform for use in building experiences or segments or to deliver reporting. In addition, we will reject any custom fields added to an event and the whole event will be lost.

Requesting a schema extension

Refer to the outline process guidance for requesting schema extensions.

Outline process

All requests should be sent to your CSM.

  1. Submit your request for field or event changes to your CSM

  2. We will evaluate your request and either agree the change or make our own proposal

  3. Once agreed, we will make the necessary schema changes

  4. Check for dependencies in experience code, etc and mitigate

  5. Data can now be sent using the agreed schema extension

  6. We will implement the necessary changes in your property configuration

  7. Validation checks to ensure events are being emitted correctly and that data is being collected without error

For new events

Note

Any custom events you require must be namespaced. In most cases, this should be your property name, without spaces and in lowercase and the name of the custom event, e.g. myproperty.ecView, anotherproperty.myCustomEvent. This convention must be used consistently for all the custom events you wish to emit.

When extending QProtocol with new events, it is imperative that checks are performed to ensure that references to events in your experience or segment code have been written in a way that will support the new event name:

Specifically, events that were bound to the event name, will need to be converted from this:

uv.on('ecView', event => {})

to a namespace specific convention:

uv.on('namespace.ecView', event => {})

or a namespace agnostic approach using regular expressions:

uv.on(/ecView/, event => {})

For new fields

Note

Once a new field has been added, it can’t be updated. It can only be deprecated.

To extend an event with a custom field, share the following information with your CSM:

  • Field name: Use a specific and meaningful keyword using camel case (for example, accNo and not accno or acc_No or acc_no).

  • Position inside the QP event - fields can be nested, so specify the exact position. Use dot notation to indicate a nested path hierarchy for a field.

  • Type: only the following types are allowed: String, Number, Float, Boolean, and StringArray.

  • Short description

  • Value example

  • Whether the field contains PII

As an example, let’s say you want to add a custom value about the visitor’s favorite color inside the ecUser event. You should provide the following information:

  • favoriteColor

  • user.favoriteColor in ecUser

  • String

  • This field contains the favorite color (maximum one) of the visitor.

  • Blue

  • This field doesn’t contain PII.