10. Data Definitions

  • Description
  • Resources
  • Lessons

Lesson Overview

This comprehensive course covers everything you will need to become a Manage power user - from deploying tags, data layers and event tracking to organizing your TMS strategy and properly QA and troubleshoot.

Learners should have a basic grasp of client-side web technologies.


Hello. Welcome back to the Ensighten Manage Training Series. Today we'll be discussing data definitions which, if you're here for a refresher after some years away, they were previously known as the Ensighten Data Layer or EDL. The name change was due to how confusing it might seem to have both an on-page data layer and an Ensighten Data Layer and it was a bit of a misnomer anyway since the data definitions don't actually create or store data on their own.

Data definitions are more accurately described as a data intake and manipulation process. Rather than having dataset in them like the variables of a data layer, the data definition picks up the data and, if necessary, modifies it before making it available for easy use by other tags. In some ways, this is another abstraction layer on top of the one already created with an on-page data layer but I promise it has some important uses. Before I get going, I do want to caution that the creation and handling of data definitions is something of an advanced topic. A good foundation in JavaScript and HTML is a boon in advanced configuration scenarios.

Let's start in the UI and we'll build up to the use case where the benefits become clear. You'll see the normal search and sort options are present as they were in the tags and conditions. In the details view you'll find the extraction, transformation and trigger boxes which I'll explain momentarily and some familiar boxes like history, conditions, spaces and tags. The creation of a data definition has a lot of build options and some can be quite complicated. You'll find that each of the four options here at the top offers a dropdown asking where to get the data from. A first-party cookie is any cookie that's accessible via read and write from the page.

The query parameter is the last portion of the current URL following the question mark symbol. Metadata tag refers to a meta-HTML tag on the page. JavaScript variable is exactly as it sounds, the name or full reference of a nested object of a JavaScript variable on the page. Web page element allows you to define the CSS selector to search for an element and then three refining options to choose a value from the located HTML element. And finally, custom allows you to define a function in JavaScript that should return your desired output. All of these options will generate code either on your behalf or because you provided it into what's called an extractor function. Remember how I said the data definitions are an intake process? The extractor function is what's performing that intake.

Once you've filled in the data extraction source, you'll also see the box for modify value. Checking this gives you another dropdown with options and custom at the end in case they don't fit your needs. This is the transformation box you saw on the details view and serves to modify the value you retrieved via extraction should you need to do so. Then there's the advanced settings options here. First, you'll see a persistence dropdown which lets you govern whether the extracted value of your data definition will be stored as a cookie for the length of the user session or a full year or only exist during the lifetime of a page the user is visiting.

The difference between the instance and page options are that the instance will reevaluate its extractor function every time that it is called while page will only evaluate once and use the page stored value. Next, the trigger dropdown helps you decide when the extractor function should run. The default here is bottom of body which is the same as DOM ready or once the page is interactive from our tagging options. The options should be self-explanatory accepting the reappearance of custom. Selecting custom here gives you another chance to write JavaScript to meet your own specific needs. This particular box is special in that it only properly functions when using something called promises. This can be a tricky topic so if you're not already comfortable with promises, I would advise you ignore this custom box entirely.

If you are, then setting up a promise and resolve function here should already be clear to you. For the sake of your general knowledge, a promise setup here allows you to define a very specific and sometimes multilayered resolution decision so you know exactly when and why your extraction function is executing. Following the implementation steps, you continue to a space selection field. And you can define if the data definition is available on all spaces or some subset. Next, you'll see the condition step which follows the same logic as our tagging conditions you saw on a previous video. With your spaces and conditions selected wrap up the configuration by clicking save at the bottom.

Now that you have a data definition set up, we'll return to tags and fulfill a promise I made to you previously. You recall inside the apps many of the fields come with a dropdown that allows you to choose the method by which your variable is set and one of those options is Ensighten data layer. This should probably be updated to read data or data definition in the future and by the time you're watching this, perhaps that's what it says. When you select this option, you'll find the input field changes to select an element and clicking that, you'll see a list of all data definitions. Selecting one of the options here automatically sets this tag up to use that data definition's extraction function as a source for the data in this field.

One of the huge reasons this is useful is because you may or may not be the only user in your account. Data definition's easiest and most obvious use case is making readily available a piece of data that requires some JavaScript knowhow to retrieve. With the data definition set up any user can now create tags with complex variable requirements regardless of their individual coding skill. By having your professional services rep at Ensighten or a developer on your side set up data definitions ahead of time you empower your other teams like marketing and sales to develop and deploy their own tags with advanced data requirements. This dropdown isn't the only way to call a data definition to a tag but it is certainly the simplest. I'll hop over to a custom JavaScript tag and show you a few more.

Here we are in a new custom JS tag. Let's say that I want to call a pixel and send some data to my server for analytics purposes. I'll be setting up a simple pixel call but I need to gather the data first. There are four JavaScript options to invoke a data definition in your tagging. First, there's an alias that comes with a built-in helper if you're not certain of the name or ID of your data definition. The syntax begins with two percent symbols and the word data. Then you'll see the UI helper pop up with a list and you'll be able to select the one you want. Be sure to close your alias with two more percent symbols or it won't work. When not using the alias, you can make a direct reference so long as you know the full name or ID of your data definition and there are both asynchronous and synchronous methods for this option.

An important note. By invoking these calls by hand, you bypass the data definitions' configured timing options such as bottom of body or a custom promise set up. Asynchronously, if you pass in an array of string ID values and a callback function with one argument per string in your array, the callback function will retrieve your values and store them in that callback function document.

Synchronously, you simply don't supply the callback function and you can pass in a string without the array brackets and that can be either the ID or a friendly name that follows the syntax source dot collection dot name. Source is always going to be manage. Collection and name are defined during your data definition creation process. This will always return the data definition's output but if it wasn't already a string, it will be now. If you passed in an array, you can supply multiple IDs or names and you will receive an array of strings back. Most of the time you're using data definitions it will be for apps with the helpful dropdowns so I wouldn't worry if that last part about the JS calls went over your head.

That's all for the data definitions video. Next up, we'll be covering custom and generic tagging.