Pro Mode Configurations

Data Layer Manager Pro Mode Configurations

Data Layer Manger is provided free of charge with foundational functionality which will suit most users. Extended functionality is provided to authorized users via "Pro Mode". By default, Pro Mode is locked as indicated by the lock icon and the greyed out feature areas.

Pro features may be enabled by your Search Discovery Account Manager. When Pro features are unlocked you will see messaging in the header of all extension views (as shown below).

JSON Schema Validation

After providing an Event name in the Configure Event Names section, clicking the Add JSON Schema link will open a JSON text editor. Here, a JSON Schema may be entered (or pasted in). This schema is used by Data Layer Manager to validate Event Objects as they are pushed onto the data layer. Examples of what this validation can detect:

• The absence of required attributes

• Passing incorrect data types

• Passing of string values not matching prescribed patterns

• Passing values outside of an allowed set of values

• Passing unexpected additional attributes

• Passing numeric values below a stated minimum

• Passing numeric values above a stated maximum

Below is an example JSON schema for a "Product Viewed" event.

At runtime in Launch Development and Launch Staging environments, each Event Object is validated as it is being processed. Validation Errors are exposed in the dev tools console as shown below. In this example, the validator found three issues with the "Product Viewed" Event Object that was pushed.

Note that these validation messages will only show in the console if Launch Debug mode is enabled. Enabling Launch Debug mode is very easy with the Launch and DTM Switch Chrome extension.

An application developer, upon seeing these validation errors, will know immediately that there is an issue with the Event Object that was pushed. Beyond that, the exact details of the exception are clearly presented. Even if Launch Debug mode is not enabled, the validation output is attached to each data layer event object (on __meta.validationResult) meaning that it can be accessed programmatically.

Reset Before Data Layer Event

This option is provided for any configured event, but is most likely to be used on a select few. When Reset Before is selected for a configured event, the data layer will be cleared of all values just before the event is pushed.

Event Lifecycle Hooks

Event Lifecycle Hooks provide a way to register functions which will be called as part of the event lifecyle. These functions may be used to monitor or modify event objects "in-flight" at run-time. They are processed between the time that an event is pushed to the data layer and before event validations are performed. Below is a diagram of the full event lifecycle followed by a zoomed view of the processing for Event Lifecycle Hooks.

Data Layer Manager Event Lifecycle Flow

Lifecycle Hook Processing (zoomed image)

The general rules for Event Lifecycle Hooks are detailed below:

• Registered functions receive one argument - the event object.

• Registered functions must return an event object (typically a modified version of the one passed in)

• A function may be registered against one or more events using the eventMatch regular expression.

• Multiple functions may be executed against any event.

• The execution order of these functions is determined by the executionOrder parameter that is specified when the event is registered.

As an example, imagine that we have a "Product Added" event with a payload which includes product info, pricing, and quantity but does not include an extended price attribute that is needed for a 3rd party marketing pixel. We can create a function to calculate and append the extended price. We can register this function to be called whenever the "Product Added" event is pushed. The snippet below illustrates this.

appEventData = window.appEventData||[];

//Calculate and append an extended price to each product object
var calculateExtendedPriceFn = function(dlmEvent) {
  console.log(JSON.stringify(dlmEvent, "", 2));
  dlmEvent.product.forEach(function(ep){
    ep.extendedPrice = "" + 
    ((parseFloat(ep.price.sellingPrice) + parseFloat(ep.price.monogram) + parseFloat(ep.price.logo)) *
    parseInt(ep.quantity))
    .toFixed(2);
  })
  return dlmEvent;
};

//Register the event lifecycle hook
appEventData.push({
  "preValidationCallback": {
    "func": calculateExtendedPriceFn,
    "eventMatch": "Product Added",
    "executionOrder": 10
  }
});

Note that our function, calculateExtendedPriceFn, receives the event object, modifies it, and returns the modifed event object to Data Layer Manager.

Note that this function is registered as a lifecycle hook by pushing a preValidationCallback object to the the managed data layer array.

Having registered the lifecycle hook for events matching "Product Added", we are all set for any subsequent pushes of this event.

// Example "Product Added" event being pushed...
appEventData.push({
  "event": "Product Added",
  "product": [
    {
      "quantity": 3,
      "productInfo": {
        "sku": "HC30ABJ786-XL-GRN",
        "productID": "HC30ABJ786"
      },
      "price" : {
        "sellingPrice" : "124.20",
        "monogram" : "5.00",
        "logo" : "9.50"
      }
    }
  ]
});

When the event above is pushed, and the lifecycle hook executed, our actual data layer looks like this (Note the new attribute, appEventData[3].product[n].extendedPrice)

Registering Event Lifecycle Hooks

Lifecycle Hooks are registered by pushing a preValidationCallback event onto the managed data layer array. This object takes the following form with 3 required options:

{
  "preValidationCallback": {
    "func": <function>,
    "eventMatch": <regularExpression as string>,
    "executionOrder": <executionOrder as integer>
  }
}

• function is a reference to a function declared prior -or- an inline function declaration.

• eventMatch is a string that is interpreted as a regular expression.

  • Specifying the exact name of a event is the most common use.

  • Patterns may be specified -

    • "*" would register the function to execute for all events.

    • "Product*" would register the function to execute for all events that start with "Product".

• executionOrder is an integer that allows control of excution when multiple callback functions are registered for the same event. Callbacks are processed from low to high executionOrder