DEV Community: Alexis Cazes

Tagging and Feature Flags

Alexis Cazes — Thu, 11 Aug 2022 15:22:16 +0000

This post is part of a series about auto-tagging

Feature Flags or Feature Toggle is a common practice used by developers. It allows to deploy specific functionalities in an incremental manner and only enable them when needed.

In the tagging world feature flags is a little-known concept. Most of the time a standard tagging release will consist of creating the tag, testing it with the tag management system dev endpoint then publishing it to production. This means that sometimes the release timing is crucial as it needs literally to be done at the same time as the new platform feature has been released to production so it does not impact user experience.

What are feature flags?

Feature flags are a development concept that allows to wrap a functionality inside an if condition that checks a specific variable value. This variable is usually a Boolean, so the possible values are either true for enable my feature or false for disable my feature. This allows the development team to deploy part or a full feature in an incremental manner. By doing so you can then enable/disable a feature during runtime without a code release.

if (featureFlags.feature1 === true) {
    executeCode();
}

By doing so you can allow the development team to deploy a feature to production and complete the QA process before making the feature available to your users.

If the feature relies on multiple teams to complete their work, this allows your tagging and development team to work in parallel without having to wait on each other.

Are Tagging and Feature Flags incompatible?

One might think that tagging is as simple as deploying a script tag on a platform, however it does require some planning and orchestration to make sure the tags fire in the correct order, at the right time and with the right configuration. Tags configuration can become really complex based on the business needs and the layout of the website.

If you look at how tag management systems work you will find that feature flags are being used in tags configuration without the tagging team realising it.

TMSs, like Adobe Launch, are usually structured around these 3 main sections:

Triggers: these are the events that needs to be fulfilled in order for the tags to be eligible for execution. Most TMS provides events like DOM events, custom events or directly call the tag.
Conditions: even if the event is fulfilled it does not necessary mean that we want the tag to be executed. In most instances we will provide a set of conditions that need to be met to execute the tag
Actions: this will be the list of actions or scripts that will be executed when the tag is launched.

In a sense, the conditions section can be considered as the feature flag section. But unlike traditional feature flags they are only usable by the TMS during its runtime. These conditions are most of the time scoped to the TMS object and cannot be evaluated by the platform scripts.

Now that we have understood that the feature flags concept is being used for tag configuration, the next step will be to figure out how to expose the feature flag functionality to be used outside of the TMS runtime. Our goal is for the feature flag to be set and ingested during runtime by our TMS, our platform scripts and any third party vendor scripts that we deploy on the platform via the TMS.

To achieve this, we will need to have one common location where these feature flags can be set and accessed. Luckily for us we have defined a generic data layer which is the ideal candidate to host our feature flags.

In the next section I will describe how we can extend our generic data layer to support the featureFlags property.

Extend the generic data layer to support feature flags

Luckily for us the generic data layer is a nested type data layer with a root of an object that can be easily extended.

This is an example of how our feature flags will be defined:

var digitalData = {
    "featureFlags": {
        "featureName1": true,
        "featureName2": false,
        "overWrite": {
            "featureName1": false,
            "featureName3": true
        }
    }
}

We can clearly see that we want to extend the root object to contain a new featureFlags property. This property will be an object.

To support future use cases, we will have 2 feature flag levels:

The first level will be used by the development team to set default behaviours. This will be optional as by default if a feature is not defined on the first or second level it will be considered to be disabled. An example of use case would be when a tagging release introduce a new product that should only be executed at runtime when the platform migrates to a new design. As the release of the platform will be outside of the business hours, the feature flag will need to be enabled by the development team. The tagging team would have released their build with the configuration to support the new product, days or weeks or even months before the live date.
The second level in the overWrite object will be used primarily by the tagging team. This will allow the business to be in charge to enable or disable specific features as required in the least amount of time. This level will prevail over the first level. For example when the business wants to deploy a chat functionality on your platform, they might want to first test that the chat functionality has a positive impact on the conversion rate. Before fully committing a lot of resources for the chat functionality we want to confirm that by having it on our checkout funnel it will increase the conversion rate. This use case is best answered by an A/B test. In this use case we will deploy the core functionality of the chat via a tag from our TMS. We will add a condition that will depend on our feature flag for the tag to be executed during runtime. Now in the A/B test instead of having the chat code we just need to have 2 experiences, one for chat enabled which will set digitalData.overWrite.chatEnabled to true and one for chat disabled which will set digitalData.overWrite.chatEnabled to false. As you can see the A/B test is now simpler to compose.

Now as our generic data layer is defined using the JSON schema definition, we will extend our definition by adding the featureFlags property definition inside the top level properties property:

{
    "properties": {
        "featureFlags": {
            "type": "object",
            "properties": {
                "overWrite": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "boolean"
                    }
                }
            },
            "additionalProperties": {
                "type": "boolean"
            }
        }
    }
}

Notice that the only item you will need to add to your generic data layer definition will be the featureFlags object inside your top level "properties" property.

Feature flags benefits

Now you might be wondering why we will spend time and effort to create a feature flag functionality that is already covered by the conditions section of our TMS.

One of the main limitations of the conditions section of your TMS is that the conditions can only be evaluated by your TMS. This means that your platform has no indication if a specific feature is enabled or not.
Some personalization products deployed on your platform will sometime require the development team to deploy custom components to create an optimal user experience. In order for the platform to know at runtime which component to display in the journey, they will need a feature flag. However, as the conditions section of your TMS is not globally accessible and we do not want to create technical debt by adding code from the TMS object into our platform code then the feature flag functionality is the best option.

Here are some other benefits when using globally scoped feature flags with your tagging implementation:

QA process: while it is possible to use development and staging libraries of your TMS at runtime by using a browser extension, this is not necessary the best option for your QA engineers. Some of them might not know how your TMS work and how to enable this or simply if you are in a financial company, they might not get the rights to install any browser extension. By using feature flags, the QA engineer can switch on and off the functionality and validate that it works as expected. This will also be much easier to create automated tests as the only requirement would be to set the data layer feature flag to true of false for the test. This can be achieved using local overwrite using localStorage functionality or query parameters.
Conducting experiments: in most TMSs there is no functionalities or limited functionalities to run a tag for a specific subset of your audience. At that point you will need to make a call to either deploy your functionality for all users which might result in unnecessary cost as it will ultimately not increase the conversion rate. By using a feature flag, you can release your tag to production and then control who can see/use it by creating A/B tests using your A/B test product like Adobe Target. The test will have 2 experiences, one which will enable the feature flag and one which will disable the feature flag.
Migration: in some instances your platform will have a staggered migration to a new system or new capabilities that will impact your tagging implementation. You can either do your best to keep up with your development team releases and understand which part of the platform will be impacted in a specific release or you can create 2 tags one for each version and ask your developers to switch the legacy feature tag off and the new feature tag on when they deploy the new content for a specific section of their platform. This way no downtime will be experienced by your users.
Minimize the risk to switch off a functionality completely: it is unlikely that your tagging team is only composed of yourself. It might be that multiple persons work at the same time and on different sections of the platform to deploy the same functionality. It can be that the tag conditions may vary between one section to another therefore it will be quite difficult in some instances to completely switch off a specific functionality. By using a feature flag, you can centralize on how you wrap/conditions the tags for a specific product in your tagging implementation.
Continuous deployment: in some instances, you will need to release several products together in your tagging implementation. It might take months for all the products to be setup before your get the configurations for each product and it will therefore delay your implementation work. It can also result in a massive build by the time you configure all of your products. One approach would be to configure each tag as the configuration comes available and wrap it inside a feature flag. You can then deploy this configuration to production. Once all the products have been deployed to production you can then enable the feature flag. Prior to pushing it live you can use the feature flag to test your implementation.

Using a feature flag approach will allow your business to run campaigns in an agile way where you can stop/start any functionalities without waiting on your development team to do a release. Your tagging build can be pushed to production before the platform release date.

It also provides a new type of collaboration between your development and tagging team where specific components can be created for specific use case. These components can then be displayed based on values of specific feature flags at runtime.

Real life example

A good example would be the surveys displayed on your website.
Traditionally you will use your TMS to inject your survey script code when the customer reaches a specific milestone like a page in your application. This will result in the survey being displayed on the page before your customer can see the content of the page which results in a bad user experience.

An easy fix for this issue would be to provide a button when the customer completes/close the application which will give an option to take the survey. To do so your development team will need to display this new component whenever and wherever the business wants the survey.

As the content of the survey can change at any time due to regulations, we will need to rely on something other than the development release cycle to switch on/off the survey.

The best option would be for:

your development team to create a component that will push an event to our data layer indicating that the user chose to see the survey
tagging team will configure a tag to watch for this specific event and then trigger the survey code
the developers will evaluate as the application loads if the feature flag to enable the survey is present and use the survey component if the feature flag is enabled.
the tagging team will be the one that will switch the feature flag on/off as the business needs it as they are not bound by the development release cycle.

Feature flags and testing

In order for us to be able to test specific product/feature behaviours, we need to be able to switch a feature flag on/off without having to do a release. This means that we want to overwrite the feature flag value after the tagging library is loaded and application library is loaded.

To overwrite the values set we can use 2 routes:

use localStorage to store our new configuration. When the application loads, the TMS will check the local storage and merge its configuration to the featureFlags object.
use URL query parameters to provide specific configuration. You will need to decide is query parameters will prevail over local storage overwrite during testing.

By doing so this will allow us to test both the scenarios with the feature on and off without having to a tagging or development release each time. This is particularly useful for your QA engineers to validate their tests.

Conclusion

We have seen that in its core tagging revolves around TMS based feature flags (conditions). While it is a viable approach and is mainly used, there is additional benefits to adopt a more traditional approach around globally scoped featured flags. These feature flags allow additional A/B test capabilities, tailored custom implementation to improve customer experience and a better QA process.

Generic Data Layer

Alexis Cazes — Mon, 17 Jan 2022 08:30:52 +0000

This post is part of a series about auto-tagging

While using a tag management system (TMS) like Adobe Launch, you can use different tagging methodologies to achieve your requirements. There are 3 main concepts of tagging which are:

DOM scraping which uses the functionalities of the DOM API to gather the data from the web pages. While it is a fast and flexible approach, it is also fragile as any changes in the DOM can break your implementation without notice.
Direct Call Rule which involves calling the rule/tag directly from your platform code. This approach is less flexible than the DOM scraping one. It is more robust and allows you to streamline your implementation. One of the main issues with DCR implementation is that in most instances there is no defined data structure and it also requires you to use the reference to the TMS object in your platform source code which will become a huge technical debt.
Data Layer which allows you to define a JavaScript object which will contain a structured version of the data you need to collect. While it is in the same spirit as the DCR implementation, it has the benefits to not make any reference to the TMS object which removes the technical debt issue. You can also define a well structured object to meet all of your tagging needs.

What is a data layer?

A data layer is a data structure which allows you to categorize, capture and display the data in the most efficient way. As part of the tagging effort, you will be required to deploy analytics, personalization and marketing tags. In most cases each of these products will be provided by a different third party, and each of them will require the data to be passed in a specific format.

The data layer will allow you to expose client-side the details that will be required for the tagging implementation to work in the most efficient way.

It is stored in a JavaScript object that you can access at the window level. Each provider, may it be Google or Adobe, will have their own definition of the data layer. While it fits the requirements for the specific provider it will most likely not be flexible or portable for other providers. For this reason, you should define your own data layer definition.

Flat vs nested data layer

Data Layer structures come in different forms and shapes, some more complex than others. You can choose between two distinct types of data layers.

A flat data layer consists of a JavaScript object where each property is not an object. It can be a string or a number or a boolean or an array. Each properties are on the same level and when you access the data in your code, you just need to use window.myDataLayer.property1. While it seems that a flat data layer will be simpler to implement, it is in fact harder to maintain and consume. Unlike a nested data layer, you will need to keep in mind that each property needs to have a detailed naming.

i.e: for each page data entry point you will need to add page to the name of the property to understand that the detail is related to the page. So pageName, pageURL, pageQueryString.

A flat data layer does not have a concept of object-oriented programming so you cannot group data in data category type easily. It becomes harder to check the data layer state the more the data layer structure grows.

Unlike flat data layer, nested data layer is based on object-oriented programming. A property can be of any type and it is easier to group data in specific categories. It is also easier to define, maintain and extend a nested data layer. As you will define objects, it is therefore easier to add a new property to this object rather than figuring out if a property already exists to capture this data somewhere in the flat data layer.

//Flat
var digitalData = {
    pageName: "My page",
    pageUrl: "www.domain.com/something",
    pageQuery: "?param1=value",
    brand: "Brand1",
    userAuthenticated: true,
    userId: "111",
    userType: "Type1",
    siteSection: "Section1",
    siteBusinessArea: "Area1"
}

//Nested
var digitalData = {
    page: {
        name: "My Page",
        url: "www.domain.com/something",
        query: {
            string: "?param1=value",
            params: [{
                name: "param1",
                value: "value1"
            }]
        }
    },
    site: {
        brand: "Brand1",
        section: "Section1",
        business: {
            area: "Area1"
        }
    },
    user: {
        authenticated: true,
        id: 111,
        type: "Type1"
    }
}

I will advise to always use a nested data layer. We want to be able to easily maintain and extend our data layer. We also want to easily inspect our data layer in the developer console. A nested data layer will allow you to navigate directly to the data type you want to validate instead of going through the list of all properties in the data layer object. So if you want to check all the details about page, then you simply need to navigate to this object in the data layer and you are sure you will not miss any data.

Array vs Object data layer root

For the nested data layers, you can either choose your data layer to be an array of objects or an object. If you have searched for data layer definition previously you would have seen both approaches. While both are viable you just need to consider which approach suits you best.

If you choose the array approach, you will have to push the persisting and the event data together each time an event/action happens. This means you will need to store the data somewhere so it can persist from one event to another one.

If you choose the root to be an object then you will need to make sure that each time a new action/event happens, all properties present in the object are either updated or removed as required. In this approach you can persist data directly in the data layer object and only remove them for specific logic.

i.e: if you have an application object, you need to make sure to remove it from your data layer if previous event was an APPLICATION COMPLETE. This means that new event should not have any application data present, failing to do so will inflate your application complete metrics.

You will also need to have a property that will be an array. This will be used as a notification layer so that you can easily watch for any changes in your data layer.

Define a generic data layer

Now that I have explained the different types of data layer, I will now explain how to achieve a generic definition of a data layer.

One of the main mistake in medium to large companies is the lack of a unique data layer definition across the company. In most cases each business area will operate in their own development cycle with their own development team. When you as a tagging member will request a data layer, they will fulfill your request but it is unlikely they will use the same property naming of same values for same outcome.

One simple example which I experienced was for the same platform but different product type, one cell put the applicationStatusCode as COMPLETED and another one as COMPLETE. In this instance, this meant that for one cell the implementation would have had application complete metrics in analytics while the other did not as COMPLETE was not supported in the tagging logic.

By defining a generic data layer definition across your company, it will allow you to achieve better data quality, efficient tagging and in the long run you can implement auto-tagging across the different business sections as same data structure will be expected for specific actions/events on the website.

Naming convention

Let’s define some data layer naming convention out of the box.

snake_case vs camelCase : I always prefer camelCase naming convention and that what we will use for the names of our properties.
do not repeat category name inside nested object. When using nested data later type it is not necessary to repeat the data category type in the object properties. For example, if you have an object as page, there is no need to use pageName inside the page property. Simply use name for the nested property and in your code using page.name is cleaner than using page.pageName as we already know we are navigating through the page object.
do not use leading underscore for property name
make property names as generic as possible, we want to reuse them across all your platforms. So do not name them related to the platform.

Use JSON schema definition to define your data layer

One of the main challenges that you will faces is to choose the right way to share the data layer definition across your company.

In my early attempts I used Confluence to document my data layer definition. While it worked initially it became soon really complex to maintain as I had to update multiple pages when adding a property (I used one page per object, so I needed to update the child then all of its parents each time).

I then stumbled upon JSON Schema Definition. This will allow you to define your data layer in a detailed and logical manner. You can provide the definition directly to your developer that should easily understand what is required, what are the limitations and which validations needs to be ran.

Our generic data layer

For our generic data layer, we will use a nested data layer. This data layer will have a root of an object. Each property can be of any type including an object. Each type of data should be defined as its own object. To future proof it we will make sure to create an object for each type of data category type even if it will contain one child property, this will allow us to easily extend it in the future.

We want to have a version property to keep track which version of our data layer is deployed on the platform. We also want to gather data about the page, site, server and user. As a notification layer we will use an events array. These properties would be our base data layer implementation and should be present in every single events.

var digitalData = {
    version: "",
    page: {},
    site: {},
    events: [],
    user: {},
    server: {}
}

{
    "$schema": "https:/json-schema.org/draft-07/schema#",
    "type": "object",
    "required": [
        "version",
        "page",
        "site",
        "events",
        "user",
        "server"
    ],
    "properties": {
        "version": {},
        "page": {},
        "site": {},
        "events": {},
        "user": {},
        "server": {}
    }
}

From now on I will define each required properties one by one. We will update the definition under the properties section of the JSON schema definition above. Each sub object will be defined in the same manner as the root one, we will define its type, what is required and the properties it may contain. We might also add enums which will list the only supported values and description so whoever reads this definition understand what this property should be.

version

The version property should always contain the latest version of our data layer. We will use vMajor.Minor.Patches notation. i.e: v1.0.0. Major should not be changed unless the release is breaking changes and will require a major refactoring. Minor should be incremented each time a new feature or main property is introduced like for example form which is not present in our current definition. And patches should be incremented each time you provide a fix to the definition.

So, for the version definition it will be as follow:

{
    "type": "string",
    "title": "Version of the generic data layer",
    "description": "The generic data layer is versioned to keep track of its changes, correct version needs to be specified",
    "enum": [
        "v1.0.0"
    ]
}

server

The server property tracks the details about the platform that delivers the website. For the name you should put the code name that is used internally to identify the project or platform.

So, for server definition it will be as follow:

{
    "type": "object",
    "title": "Server details",
    "description": "Provide details of the current platform",
    "required": [
        "name"
    ],
    "properties": {
        "name": {
            "type": "string",
            "title": "Server name",
            "description": "Name of the platform serving the website, needs to be unique.",
            "examples": [
                "Project1",
                "ABC",
                "Platform 1"
            ]
        },
        "version": {
            "type": "string",
            "title": "Server version",
            "description": "Can either be the version number or the release code name"
        }
    }
}

page

The page property will be used to track details about the current and previous page. We want to know its name, URL, query params, fragments and type. For type and name, agree with your developers to provide meaningful values.

So, for the page definition it will be as follow:

{
    "type": "object",
    "title": "Page details",
    "description": "Contains all details about current page loaded and previous page",
    "required": [
        "name",
        "url",
        "previous",
        "query",
        "fragments"
    ],
    "properties": {
        "name": {
            "type": "string",
            "title": "Page name",
            "description": "Page name will be reported as is. Needs to be unique"
        },
        "url": {
            "type": "string",
            "title": "Page URL",
            "description": "Full URL of the page loaded with query string parameters and fragments. Any sensitive data needs to be stripped out"
        },
        "previous": {
            "type": "object",
            "title": "Previous page details",
            "description": "Details of the previous page loaded",
            "required": [
                "name",
                "url"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "title": "Previous page name",
                    "description": "Previous page name will be reported as is. Needs to be unique"
                },
                "url": {
                    "type": "string",
                    "title": "Previous page url",
                    "description": "Full URL of the previous page loaded with query string parameters and fragments. Any sensitive data needs to be stripped out"
                }
            }
        },
        "query": {
            "type": "object",
            "title": "URL query string parameters details",
            "description": "Provide details of the query string present in the URL of the page loaded",
            "required": [
                "string",
                "parameters"
            ],
            "properties": {
                "string": {
                    "type": "string",
                    "title": "Full query parameters",
                    "description": "Should display the full query string parameters without the initial ? and without fragments"
                },
                "parameters": {
                    "type": "array",
                    "title": "Array of query string parameters",
                    "description": "This array should contain all query string parameters present in the URL of page loaded",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string",
                                "title": "Query String param name",
                                "description": "Name of the query string param name"
                            },
                            "value": {
                                "type": "string",
                                "title": "Value of the query string param",
                                "description": "Value of the query string param"
                            }
                        }
                    }
                }
            }
        },
        "fragments": {
            "type": "string",
            "title": "URL fragments",
            "description": "Display the full URL fragments"
        },
        "type": {
            "type": "string",
            "title": "Page type",
            "description": "Provides the page type.",
            "examples": [
                "HOME",
                "PRODUCT",
                "SUPPORT"
            ]
        }
    }
}

site

We also want to know the details about the site that we are on. Site data is generic to any type of implementation and can be easily reused.
We want to know which brand is being used. In some cases, some platforms use the same code but a different branding is displayed. However the underlying content and logic of the website is exactly the same.
It is also good to know how we reached the site. This is useful if you have a mobile app and a website. It can be that the user can access same content by being redirect from your app or from your website.
We also want to know which section of the site is being browsed.

So, for the site definition it will be as follow:

{
    "type": "object",
    "title": "Site details",
    "description": "Contains all the details about the website/platform loaded",
    "required": [
        "brand",
        "section",
        "channel",
        "business"
    ],
    "properties": {
        "brand": {
            "type": "string",
            "title": "Brand",
            "description": "The brand of the website"
        },
        "section": {
            "type": "string",
            "title": "Site section",
            "description": "Site section of the website",
            "examples": [
                "Section 1",
                "Sales"
            ]
        },
        "channel": {
            "type": "string",
            "title": "Site channel",
            "description": "Represent by which channel the customer reached the website",
            "enum": [
                "ONLINE",
                "MOBILE"
            ]
        },
        "business": {
            "type": "object",
            "title": "Site Business details",
            "description": "Contains all details about the website business section",
            "required": [
                "area"
            ],
            "properties": {
                "area": {
                    "type": "string",
                    "title": "Business area",
                    "description": "Represent the business area of the website",
                    "examples": [
                        "Personal",
                        "Business"
                    ]
                }
            }
        }
    }
}

user

We can gather some generic data about the user that browse your website. By default we can track if the user is logged in or logged out. You can also provide details about the user category and type.

So, for the user definition it will be as follow:

{
    "type": "object",
    "title": "User details",
    "description": "Provide all the details about the user of the website",
    "required": [
        "authenticated"
    ],
    "properties": {
        "authenticated": {
            "type": "boolean",
            "title": "User authenticated state",
            "description": "Should be set to true if user has logged in to the website"
        },
        "id": {
            "type": "string",
            "title": "User ID",
            "description": "ID of the user using the website, should be a non PII data"
        },
        "type": {
            "type": "string",
            "title": "User type",
            "description": "Type of the user",
            "examples": [
                "youth"
            ]
        },
        "segment": {
            "type": "string",
            "title": "User segment",
            "description": "If the user type is not enough to define the user, the segment should also be provided",
            "examples": [
                "minor",
                "adult"
            ]
        }
    }
}

events

The events property will be used as a notification layer. This will be an array. It will be updated last when updating the data layer. By doing so we will notify that the data layer state has been fully updated due to a specific action/event.

As our data layer use an object as root, it means that it is possible for the state of the data layer to quickly change (i.e: page will change really quickly when a form is submitted from the FORM COMPLETE event to the next PAGE LOAD event.).

First let’s discuss about potential events/actions that may happen on your website:

we can have a PAGE event. For now, the default phase we want to notify for is LOAD.
we can have an APPLICATION event. The only phases we want to notify for are START and COMPLETE (either successfully or unsuccessfully). We will also define an application object later on to provide further details on the application state.
we can have a FORM event. The only phases we want to notify for are START, COMPLETE and FORM_FIELD_ACTION. FORM_FIELD_ACTION should be used when a field is interacted with, however if you have helper sections in your form like helper accordions then it is better to use the ACTION event. We will define a form object later on to provide more details about the form.
we can have an ACTION event. An action event is anything that we want to send a notification for but does not fall into any of the types above.

In terms of hierarchy:
PAGE
↳ APPLICATION
↳ FORM
↳ ACTION

This means that when a PAGE loads it is possible that there is also an APPLICATION START and FORM START. As it is also a PAGE LOAD then PAGE LOAD prevails. In this case we will only send one event PAGE LOAD and update the application and form property with correct phase.

Please notice that in this definition we introduce the use of allOf which allows us to define the logic and dependency between properties

So, for the events definition it will be as follow:

{
    "type": "array",
    "title": "Events array",
    "description": "Should not be reset but new events should be pushed.",
    "items": {
        "type": "object",
        "title": "Event",
        "description": "Event providing details of what happened on the page",
        "required": [
            "target",
            "phase",
            "track"
        ],
        "properties": {
            "pageSection": {
                "type": "string",
                "title": "Event page section",
                "description": "If the event is an interaction with an element then specify which section of the page was interacted with.",
                "examples": [
                    "hero",
                    "Top Navigation",
                    "Product details",
                    "Footer"
                ]
            },
            "target": {
                "type": "string",
                "title": "Event target",
                "description": "What generated this event, corresponding phase needs to be set",
                "enum": [
                    "PAGE",
                    "FORM",
                    "APPLICATION",
                    "ACTION"
                ]
            },
            "phase": {
                "type": "string",
                "title": "Event phase",
                "description": "For each specific target, a specific phase is available. See allOf definition."
            },
            "track": {
                "type": "boolean",
                "title": "Track event",
                "description": "Indicates if the event should be reported via analytics. Useful if some events should never be reported in Analytics."
            },
            "delay": {
                "type": "boolean",
                "title": "Event analytics delay",
                "description": "Indicates if the event should be delayed for analytics tracking"
            },
            "timeStamp": {
                "type": "number",
                "title": "Event timestamp",
                "description": "Timestamp of when the event happened."
            },
            "productId": {
                "type": "string",
                "title": "Event product ID",
                "description": "If the event is a result of an interaction with a product on the page then specify which product. i.e: Useful for checkout page to add to remove products."
            },
            "element": {
                "type": "object",
                "title": "Page element",
                "description": "Element on the page interacted with",
                "properties": {
                    "id": {
                        "type": "string",
                        "title": "Element DOM id",
                        "description": "Should be the id assigned to the element in the DOM"
                    },
                    "className": {
                        "type": "string",
                        "title": "Element DOM className",
                        "description": "Should be the className assigned to the element in the DOM"
                    },
                    "value": {
                        "type": "string",
                        "title": "Element DOM value",
                        "description": "Should be the value assigned to the element in the DOM. NO PII DATA SHOULD BE PRESENT"
                    },
                    "type": {
                        "type": "string",
                        "title": "Element DOM type",
                        "description": "Should be the type assigned to the element in the DOM"
                    },
                    "category": {
                        "type": "string",
                        "title": "Element category",
                        "description": "Element category"
                    },
                    "link": {
                        "type": "object",
                        "title": "Link details",
                        "description": "If the element interacted with is a link provide this property",
                        "properties": {
                            "destination": {
                                "type": "string",
                                "title": "Link destination",
                                "description": "Destination of the link",
                                "enum": [
                                    "External",
                                    "Internal",
                                    "On-page (no page reload)",
                                    ""
                                ]
                            },
                            "url": {
                                "type": "string",
                                "title": "Link URL",
                                "description": "Link URL"
                            }
                        }
                    }
                }
            }
        },
        "allOf": [
            {
                "if": {
                    "properties": {
                        "target": {
                            "const": "PAGE"
                        }
                    }
                },
                "then": {
                    "properties": {
                        "phase": {
                            "const": "LOAD"
                        }
                    }
                }
            },
            {
                "if": {
                    "properties": {
                        "target": {
                            "const": "FORM"
                        }
                    }
                },
                "then": {
                    "properties": {
                        "phase": {
                            "pattern": "^START|COMPLETE|FORM_FIELD_ACTION$"
                        }
                    }
                }
            },
            {
                "if": {
                    "properties": {
                        "target": {
                            "const": "APPLICATION"
                        }
                    }
                },
                "then": {
                    "properties": {
                        "phase": {
                            "pattern": "^START|COMPLETE$"
                        }
                    }
                }
            },
            {
                "if": {
                    "properties": {
                        "target": {
                            "const": "ACTION"
                        }
                    }
                },
                "then": {
                    "properties": {
                        "phase": {
                            "pattern": "^.*$"
                        }
                    }
                }
            }
        ],
        "dependencies": {
            "target": [
                "phase"
            ],
            "phase": [
                "target"
            ]
        }
    }
}

We are now ready to deploy the basic implementation of our data layer. The only events we should send right now are PAGE LOAD and ACTION. We have not defined the products, form and application property yet.

Products and data layer

It is likely that your website will use some sort of products on the page. While the page might not display the product per say, the page will be linked to a product.

i.e: During a credit card application, while each step in the application does not display the product, they are directly linked to the credit card product. We should therefore update the data layer accordingly to reference the credit card product for each step.

For our use case we will define the products property as an array of product objects. Each product will have an id, name, category id and category name.

For your implementation, check what is a proper definition of a product, which common criteria are shared across your products.

So, for the products definition it will be as follow:

{
    "type": "array",
    "title": "Products details array",
    "description": "Details of the products present on the page or interacted with or being applied for",
    "items": {
        "type": "object",
        "title": "Product detail",
        "description": "Details of the product",
        "required": [
            "id",
            "name",
            "category"
        ],
        "properties": {
            "id": {
                "type": "string",
                "title": "Product ID",
                "description": "Product ID",
                "examples": [
                    "id123",
                    "x1a2"
                ]
            },
            "name": {
                "type": "string",
                "title": "Product name",
                "description": "Name of the product as displayed for the customer",
                "examples": [
                    "Product 1",
                    "Product red"
                ]
            },
            "position": {
                "type": "number",
                "title": "Product position",
                "description": "Position of the product on the search result page. Starts from index 0."
            },
            "details": {
                "type": "array",
                "title": "Product details",
                "description": "Use this field to provide any additional details about the product",
                "items": {
                    "type": "string"
                }
            },
            "category": {
                "type": "object",
                "title": "Product category details",
                "description": "Product category details",
                "required": [
                    "name",
                    "code"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "title": "Product category name",
                        "description": "Name of the product category",
                        "examples": [
                            "Category 1"
                        ]
                    },
                    "code": {
                        "type": "string",
                        "title": "Product category code",
                        "description": "Internal Product category code",
                        "examples": [
                            "C1"
                        ]
                    }
                }
            }
        }
    }
}

Notice that we used position property here. While it is not required, it will have its specific use like when a customer can do a search and filter for specific products on your page. By analyzing the position of the specific product in your analytics tool, you might find out that if it is displayed in specific position range it is more likely to convert.

Forms and data layer

In this section we will introduce the form property. This will be used to track the interaction with a form on our website. The following form events will be tracked: START, COMPLETE and FORM_FIELD_ACTION.

In the events property we made a reference to the event type of FORM. This event type will be used for FORM_FIELD_ACTION event and COMPLETE event.

For the form START, it is possible that the form START will be part of the PAGE LOAD or the APPLICATION START in itself, therefore we will only update the form property when the form start is part of PAGE LOAD for example.

We also want to track the duration of the form. This will be a good indicator if your user struggles to complete it. Further analysis would be needed in this case to pinpoint the issue.

So, for the form definition it will be as follow:

{
    "type": "object",
    "title": "Form details",
    "description": "Provide details of the form the user is currently interacting with",
    "required": [
        "id",
        "name",
        "phase"
    ],
    "properties": {
        "id": {
            "type": "string",
            "title": "Form ID",
            "description": "ID of the form being interacted with"
        },
        "name": {
            "type": "string",
            "title": "Form common name",
            "description": "Common name of the form being interacted with"
        },
        "phase": {
            "type": "string",
            "title": "Form phase",
            "description": "Provide the details at which liefecycle phase of the form we are at.",
            "enum": [
                "START",
                "IN_PROGRESS",
                "COMPLETE"
            ]
        },
        "time": {
            "type": "object",
            "title": "Form time details",
            "description": "Provide details about the star time, end time and duration of the form interaction",
            "properties": {
                "startedAt": {
                    "type": "number",
                    "title": "Form started at",
                    "description": "Time in milliseconds of when the form started"
                },
                "completedAt": {
                    "type": "number",
                    "title": "Form completed at",
                    "description": "Time in milliseconds of when the form completed at"
                },
                "duration": {
                    "type": "number",
                    "title": "Form duration",
                    "description": "Duration in milliseconds it took the customer to complete the form"
                }
            }
        }
    }
}

Notice that for the phase we also have a value of IN_PROGRESS. The START phase should ever be set only once in the form property per form. In your implementation logic you should always switch the phase value to IN_PROGRESS if the previous value is START.

Application and data layer

If your website allows users to apply or quote for something, then the application property will allow you to describe this process. In most application we will have a START and an outcome may it be success or failure.

The application property is also the ideal candidate to be extended to provide further details about the product being applied to instead of the products object. For example, if your application is about a loan then you can extend your application object to contain a loan object with properties: amount, purpose, termMonths and termYears.

So, for the application definition it will be as follow:

{
    "type": "object",
    "title": "Application details",
    "description": "Provide all details about an application",
    "required": [
        "id",
        "name",
        "status",
        "time",
        "end",
        "start",
        "inProgress"
    ],
    "properties": {
        "id": {
            "type": "string",
            "title": "Application ID",
            "description": "ID of the application"
        },
        "name": {
            "type": "string",
            "title": "Application name",
            "description": "Common name of the application",
            "examples": [
                "My easy application"
            ]
        }
        "status": {
            "type": "object",
            "title": "Application Status details",
            "description": "Provide all the details of the application status",
            "required": [
                "code",
                "phase"
            ],
            "properties": {
                "decision": {
                    "type": "string",
                    "title": "Application decision",
                    "description": "Should be set at the end of the application",
                    "enum": [
                        "Approved",
                        "Referred",
                        "Declined",
                        "Error"
                    ]
                },
                "code": {
                    "type": "string",
                    "title": "Application status code",
                    "description": "Correspond to the status code set server side to provide details about the application status",
                    "examples": [
                        "IN_PROGRESS",
                        "COMPLETE",
                        "FRAUD_REFER"
                    ]
                },
                "phase": {
                    "type": "string",
                    "title": "Application status phase",
                    "description": "Should be set to the correct phase during the application lifecycle",
                    "enum": [
                        "START",
                        "COMPLETE",
                        "PENDING",
                        "DECLINE",
                        "EXIT",
                        "ERROR",
                        "IN_PROGRESS"
                    ]
                },
                "reasons": {
                    "type": "object",
                    "title": "Application status reasons details",
                    "description": "Provide more details on the application status phase chosen",
                    "properties": {
                        "error": {
                            "type": "string",
                            "title": "Application error reasons",
                            "description": "Reason on why application errored out"
                        },
                        "decline": {
                            "type": "string",
                            "title": "Application decline reasons",
                            "description": "Reason on why application was declined"
                        },
                        "exit": {
                            "type": "string",
                            "title": "Application exit reasons",
                            "description": "Reason on why application was exited"
                        },
                        "pending": {
                            "type": "array",
                            "title": "Application pending reasons",
                            "description": "Reason on why application was referred",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            }
        },
        "time": {
            "type": "object",
            "title": "Application time details",
            "description": "Provide details about the duration of the application",
            "properties": {
                "startedAt": {
                    "type": "number",
                    "title": "Application started at",
                    "description": "Timestamp of when the application started"
                },
                "completedAt": {
                    "type": "number",
                    "title": "Application completed at",
                    "description": "Timestamp of when the application completed"
                },
                "duration": {
                    "type": "number",
                    "title": "Application duration",
                    "description": "Duration in milliseconds of the application"
                }
            }
        },
        "end": {
            "type": "boolean",
            "title": "Application end",
            "description": "Indicates if the application reached completion. Should be set to false if start is true or inProgress is true"
        },
        "start": {
            "type": "boolean",
            "title": "Application start",
            "description": "Indicates if the application just started. Should be set to false if end is true or inprogress is true"
        },
        "inProgress": {
            "type": "boolean",
            "title": "Application in-progress",
            "description": "Indicates if the application is inprogress. Should be set to false if start is true or end is true"
        },
        "quote": {
            "type": "object",
            "title": "Application quote details",
            "description": "All quote details",
            "properties": {
                "decision": {
                    "type": "string",
                    "title": "Application quote decision",
                    "description": "Decision of the application quote."
                },
                "phase": {
                    "type": "string",
                    "title": "Application quote phase",
                    "description": "Phase of the application quote. START: should be set when application.start is true. COMPLETE: should be set if application quote is successful. PENDING: Should be set if application quote has been referred or pended for any reasons. DECLINE: should be set if application quote has been declined for any reasons. EXIT: Should be set if application quote has been existed for any reasons. ERROR: Should be set if application quote has errored for any reasons",
                    "enum": [
                        "START",
                        "COMPLETE",
                        "PENDING",
                        "DECLINE",
                        "EXIT",
                        "ERROR",
                        "IN_PROGRESS"
                    ]
                },
                "code": {
                    "type": "string",
                    "title": "Application quote code",
                    "description": "Code of the application quote",
                    "examples": [
                        "ACCEPT",
                        "FRAUD_REFER"
                    ]
                }
            }
        }
    },
    "allOf": [
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "START"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": true
                    },
                    "end": {
                        "const": false
                    },
                    "inProgress": {
                        "const": false
                    },
                    "time": {
                        "startedAt": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "COMPLETE"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": true
                    },
                    "inProgress": {
                        "const": false
                    },
                    "status": {
                        "properties": {
                            "decision": {
                                "const": "Approved"
                            }
                        }
                    },
                    "time": {
                        "completedAt": {
                            "pattern": "[0-9]{1,}"
                        },
                        "duration": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "PENDING"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": true
                    },
                    "inProgress": {
                        "const": false
                    },
                    "status": {
                        "properties": {
                            "decision": {
                                "const": "Referred"
                            },
                            "reasons": {
                                "properties": {
                                    "pending": {
                                        "minItems": 1
                                    }
                                }
                            }
                        }
                    },
                    "time": {
                        "completedAt": {
                            "pattern": "[0-9]{1,}"
                        },
                        "duration": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "DECLINE"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": true
                    },
                    "inProgress": {
                        "const": false
                    },
                    "status": {
                        "properties": {
                            "decision": {
                                "const": "Declined"
                            },
                            "reasons": {
                                "properties": {
                                    "decline": {
                                        "pattern": "^.*$"
                                    }
                                }
                            }
                        }
                    },
                    "time": {
                        "completedAt": {
                            "pattern": "[0-9]{1,}"
                        },
                        "duration": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "ERROR"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": true
                    },
                    "inProgress": {
                        "const": false
                    },
                    "status": {
                        "properties": {
                            "decision": {
                                "const": "Error"
                            },
                            "reasons": {
                                "properties": {
                                    "error": {
                                        "pattern": "^.*$"
                                    }
                                }
                            }
                        }
                    },
                    "time": {
                        "completedAt": {
                            "pattern": "[0-9]{1,}"
                        },
                        "duration": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "EXIT"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": true
                    },
                    "inProgress": {
                        "const": false
                    },
                    "status": {
                        "properties": {
                            "reasons": {
                                "properties": {
                                    "exit": {
                                        "pattern": "^.*$"
                                    }
                                }
                            }
                        }
                    },
                    "time": {
                        "completedAt": {
                            "pattern": "[0-9]{1,}"
                        },
                        "duration": {
                            "pattern": "[0-9]{1,}"
                        }
                    }
                }
            }
        },
        {
            "if": {
                "properties": {
                    "status": {
                        "properties": {
                            "phase": {
                                "const": "IN_PROGRESS"
                            }
                        }
                    }
                }
            },
            "then": {
                "properties": {
                    "start": {
                        "const": false
                    },
                    "end": {
                        "const": false
                    },
                    "inProgress": {
                        "const": true
                    }
                }
            }
        }
    ]
}

Notice that an application can start on a page load, therefore it is not necessary to send a PAGE LOAD event followed by an APPLICATION START event. Only the PAGE LOAD event will be enough, and you should update the application properties to start accordingly.

Conclusion

For tagging implementation that is built around a data layer to be successful, it is advised to define a common/generic definition that will be reusable across all your platforms.
We want our data layer implementation to be maintainable, extendable, and reusable. To do so it is important that our data layer definition is generic enough.

Build a view for your Adobe Launch extension

Alexis Cazes — Tue, 28 Dec 2021 14:12:29 +0000

This post is part of a series about auto-tagging

In this article I will describe how to create your views for your Adobe Launch extension. Extensions are a way to extend your tagging implementation to provide reusable content for your tagging team to use in all your Adobe Launch containers.

When building a private or public extension, you will be given the option to provide a configuration view for your extension or extension feature. While it is optional to provide a configuration, I will advise you to always choose this option.

As a best practice it is advised to add a view when creating a data element or a condition or a rule or an extension. Even if you are not planning to return a settings object, a view should be used to provide additional details about the feature.

Going forward I will consider that you have already ran the following command and answered yes to the question about the configuration view.

npx @adobe/reactor-scaffold

What does the scaffold command do

When we first generate the scaffold of our extension you would notice that the src folder is automatically generated for us. Inside this folder you will find the lib and view folder.

The view folder should contain all the HTML files which will be used in the Adobe Launch UI. When an extension is installed, Adobe Launch will allow you to use the actions, data elements etc... that you configured in your extension.json file. When you select in the Adobe Launch interface one of the features that you configured, Adobe Launch will fetch the corresponding HTML file and load it in an iframe. The main purpose of a view is to return a settings object that will then be used in the JavaScript file present in the lib folder.

All files in the lib folder will be present in the Adobe Launch core library that you load on your website.

Try to remove the .min from your Adobe Launch library URL and have a look. You will see the content of your js files inside it.

It is important to note that for the views to work you need to put the CSS files and any other helper files inside the view folder itself. This way when you will use npx @adobe/reactor-packager command, they will automatically be zipped.

Building our view.

By default, the scaffold command will not add any CSS to your HTML file. It is up to you to use any CSS framework that suits you best (hence the great flexibility of the extensions). This means that you can customize your extension to match your brand design.

Please note that while some public extensions available in Adobe Launch use Single Page Application framework like React to create the Views, you do not have to use any. I use default HTML, CSS and Vanilla JavaScript and it meets all my requirements.

The default HTML code will look as follow in your HTML files:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Extension Configuration</title>
  </head>
  <body>
    Extension Configuration Template

    <script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>
    <script>
      window.extensionBridge.register({
        init: function(info) {
          if (info.settings) {
            // TODO Populate form values from persisted settings.
          }
        },

        getSettings: function() {
          // TODO Return settings object from form values.
        },

        validate: function() {
          // TODO Return whether settings are valid.
        }
      });
    </script>
  </body>
</html>

In the example above, you will see Extension Configuration Template. This section can be replaced by any HTML code that you want. You can style as you want as well. Usually, you will place your configuration form in this section.

You will see 2 script tags. Do not delete them. The first one is about the extensionbridge and needs to be present.

In the next script tag, you will find:

validate

In this section you will need to create your logic to validate that the configuration values provided match the minimum requirements. You need to check if required fields have a value and if specific fields contain right values. You should always return a Boolean. true should be returned if validation is a success and false should be returned if validation is a failure.

validate: function() {
    return true;
}

getSettings

This function should be used to return the settings object which contains the configuration that will be used in the js file for the rule or data element or condition or extension.

getSettings: function() {
    return {
        test1: getValueFromField1(),
        test2: 123,
        test3: [1, 3]
    }
},

You should not add any validation logic inside the getSettings section. The validate section should be used instead. Also, you should always have corresponding validation logic inside your js file to make sure the settings object is as you would expect.

init

This is called when the view is loaded. It checks if an existing settings object exist. If it exists, you can then prepopulate the form with the existing configuration.

init: function(info) {
    if (info.settings) {
        if (info.settings.test1) {
            test1Field.value = info.settings.test1;
        }
    }
},

If your configuration view should not return any settings then you can replace it by this

window.extensionBridge.register({
    init: function(info) {},

    getSettings: function() {
        return {};
    },

    validate: function() {
        return true;
    }
});

Add your own CSS and helpers for the view

To upload an extension, you will first need to package it. Luckily for us Adobe already provides a command for this

npx @adobe/reactor-packager

For our CSS and helper JavaScript files to be part of the packager output zip file, we will need to reference them in the view folder. If they are outside there will not be available when the view HTML files loads in Adobe Launch.

You can also use CDN to deliver your helpers and CSS files. As the HTML file is loaded in an iframe, it should be safe to consider that any risks related to CDN should be mitigated.

For our example we will add Bulma CSS framework, ION Icons and some custom JavaScript helper files.

Create the css folder in the view folder
Create the js folder in the view folder
Create the helpers folder in the js folder
Go to Bulma website and download the latest build. Place the bulma.min.css in the css folder

Add the file viewHelpers.js inside the js/helpers folder

    //Support selection of data element
    function addListenerToDataElement() {
        var dataElementSelectorElements = document.querySelectorAll('.data-element');

        if (dataElementSelectorElements) {
            dataElementSelectorElements.forEach(function (element) {
                element.addEventListener('click', function (event) {
                    window.extensionBridge.openDataElementSelector().then(function (dataElement) {
                        var target = event.target;
                        while (!target.classList.contains('field')) {
                            target = target.parentElement;
                        }
                        target.querySelector('.input').value = dataElement;
                    });
                });
            })
        }
    }

    addListenerToDataElement();

    //used when missing field
    function toggleNotification() {
        document.querySelector('#error').classList.toggle('is-hidden');
    }

The folder structure should now look as follow

    > src
        > view
            > actions
            > dataElements
            > configuration
            > events
            > css
                bulma.min.js
            > js
                > helpers
                    viewHelpers.js

Go to your html files and update them to reference your CSS file and JavaScript files

<!doctype html>
<html lang="en">

<head>
<meta charset="UTF-8">
<title>Extension Configuration</title>
<link rel="stylesheet" href="../css/bulma.min.css">
<script src="https://unpkg.com/ionicons@4.5.10-0/dist/ionicons.js"></script>
</head>

<body>
    <section class="section is-hidden" id="error">
        <div class="notification is-danger is-light">
            <button class="delete" onclick="toggleNotification()"></button>
            <ion-icon name="alert" class="has-text-danger"></ion-icon> Error message
        </div>
    </section>

    <script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>
    <script>
        window.extensionBridge.register({
        init: function (info) { },

        getSettings: function () {
            return {};
        },

        validate: function () {
            return true;
        }
        });
    </script>
    <script src="../js/helpers/viewHelpers.js"></script>
</body>

</html>

Add a form to configure our extension, action, data element or condition

The view HTML file will allow you to return a settings object with the configuration to be used when the action or data element or condition or extension is executed.

There is different ways to provide settings:

you can use input fields to provide hard coded values
you can use data element selector to return a data element reference. On runtime the data element will be evaluated, and correct value will be returned. You will notice that the data element value needs to be return between % as %myDataElement%
use a code editor to return a JSON object
use a code editor to return JavaScript code to be executed as part of a function call (requires transform)

We are now going to add to our HTML file the structure of our form.

We will use the openDataElementSelector and openCodeEditor shared views to edit our code.

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <title>Extension Configuration</title>
  <link rel="stylesheet" href="../css/bulma.min.css">
  <script src="https://unpkg.com/ionicons@4.5.10-0/dist/ionicons.js"></script>
</head>

<body>
  <section class="section is-hidden" id="error">
    <div class="notification is-danger is-light">
      <button class="delete" onclick="toggleNotification()"></button>
      <ion-icon name="alert" class="has-text-danger"></ion-icon> Error message
    </div>
  </section>

  <section>
    <!--Normal field-->
    <label class="label">Normal Field</label>
    <div class="field">
      <div class="control is-expanded">
        <input id="normal" class="input" type="text" placeholder="Input a value">
      </div>
    </div>
    <!--Field with Data Element selection-->
    <label class="label">Data Element Selection field</label>
    <div class="field has-addons">
      <div class="control is-expanded">
        <input id="dataElement" class="input" type="text" placeholder="Click on icon to select your data element">
      </div>
      <div class="control">
        <a class="button is-info data-element">
          <span class="icon is-small">
            <ion-icon name="reorder"></ion-icon>
          </span>
        </a>
      </div>
    </div>
    <!--Button to edit JSON config-->
    <button class="button is-medium is-outlined is-info" id="edit-config" onClick="editConfig()">
      <span class="icon is-large is-primary">
        <ion-icon name="code"></ion-icon>
      </span>
      <span>Edit Config</span>
    </button>
    <!--Button to edit custom code-->
    <button class="button is-medium is-outlined is-info" id="edit-function" onClick="editFunction()">
      <span class="icon is-large is-primary">
        <ion-icon name="code"></ion-icon>
      </span>
      <span>Edit Function</span>
    </button>
  </section>

  <script>
    /**
     * Will open a code editor to edit the JSON value
     */
    function editConfig() {
      window.extensionBridge.openCodeEditor({
        code: window.config.source,
        language: 'json'
      }).then(function (code) {
        window.config.source = code;
      });
    }

    /**
     * Will open a code editor to edit the custom code
     */ 
    function editFunction() {
      window.extensionBridge.openCodeEditor({
        code: window.customCode.source,
        language: 'javascript'
      }).then(function (code) {
        window.customCode.source = code;
      });
    }
  </script>


  <script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>
  <script>
    window.customCode = { source: '' } //Stores custom code to be displayed in code editor
    window.config = { source: '' } //Stores custom JSON config to be displayed in code editor
    var normal = document.querySelector('#normal'); 
    var dataElement = document.querySelector('#dataElement');

    window.extensionBridge.register({
      // We need to remember to prepopulate the config forms so we can edit saved data
      init: function (info) {
        if (info.settings) {
          if (info.settings.normal) {
            normal.value = info.settings.normal;
          }

          if (info.settings.dataElement) {
            dataElement.value = info.settings.dataElement;
          }

          if (info.settings.config) {
            window.config.source = info.settings.config;
          }

          if (info.settings.customCode) {
            window.customCode.source = info.settings.customCode;
          }
        }
      },

      //We will return a custom object that will be available in the settings object during runtime
      getSettings: function () {
        return {
          normal: normal.value,
          dataElement: dataElement.value,
          config: window.config.source,
          customCode: window.customCode.source
        };
      },

      validate: function () {
        return true;
      }
    });
  </script>
  <script src="../js/helpers/viewHelpers.js"></script>
</body>

</html>

For the function part, we will also need to specify the property tranforms in the extension.json file. In our case we want our custom code to be stored in a function so that we can execute it. By default, any custom code using the code editor will be stored as a String in the settings object.

Inside extension.json add transforms property for the view:

"configuration": {
    "viewPath": "configuration/configuration.html",
    "schema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "type": "object",
        "properties": {}
    },
    "transforms": [{
        "type": "function",
        "propertyPath": "customCode",
        "parameters": ["window", "anotherArgument", "anotherOne"]
    }]
},

Notice that you can specify more than one transform action. In our case we are using a type of function on the settings property customCode. We also specify that the function can have 3 arguments when it is called.

Once the extension is uploaded, navigate to the extension or rule or data element or condition that you configured previously. You should see the form that you created. When you save the changes, the settings object will be saved when the main Adobe Launch library has been built.

Check the Adobe Launch library URL without the .min and you should see how the settings object is saved.

Use the settings object in the corresponding JavaScript file

When you create an action or data element or condition or extension configuration view using the scaffold command, you will notice that:

it creates an HTML file in the corresponding folder type of the view folder (i.e: an action will be saved in the actions folder)
it creates a JavaScript file in the corresponding folder type in the lib folder (i.e: an action will be saved in the actions folder). The file will have the same name but with an extension of .js
it updates the extension.json that tells which view to use and which corresponding js file to use.

Notice that by default the configuration view for the extension will not generate a js file. You will need to create one and reference it in the extension.js file in the main property.

In the js file you will see that it would have generated some skeleton code.

'use strict';

module.exports = function(settings) {
  // TODO Perform some action.
};

Conditions also have a trigger argument.

Please make sure to always update the arguments to contain event. Adobe Launch has it owns event object which can be leveraged in your code. It provides details about what type of rule is being used to trigger this action but it also provides event.detail which contains the metadata provided as payload when a direct call rule is triggered.

_satellite.track('myDCR', { test: 123, prop1: ['a', 'b']})

Without adding the event argument we will lose this payload. Even if you are not planning to use the event object, it is still a best practice to reference it. If you omit it, any data element which rely on the event object will not return the correct data. So you reference it for other features to use it.

You can call a data element in the code using _satellite.getVar('myDataElement', event) and in the data element view you can leverage the event object using %event.detail.test%

Now your code should look as follow:

'use strict';

module.exports = function(settings, event) {
  // TODO Perform some action.
};

As mentioned, the settings saved in the extension configuration view are not saved in a settings object passed as argument to a function. You will need to use turbine.getExtensionSettings() in your extension code to leverage the extension settings. This can be used in any JavaScript file of your extension.

Conclusion

I have now described how to create a view for your extension and use the settings configured to use in your code. Developing your own private extension will allow you to save a lot of time while tagging.

It is also in line with the DRY principle which is part of our tagging and coding standards

Adobe Launch Release Standards

Alexis Cazes — Wed, 22 Dec 2021 09:31:22 +0000

This post is part of a series about auto-tagging

Adobe Launch release process is by design simple. This simplicity sometimes comes at a cost as quality checks are often missing before code goes to production. You should also have tagging and coding standards set up to facilitate the release process.

Peer review

Adobe Launch publishing process is built in a way that your build should be approved before being pushed to production. During this approval process, you should have one of your tagging peers to review the build and validate that the tagging and coding standards are being followed.

You should also use a tool like JIRA to document the peer review process and only if an "approved" comment is present should you then release to production.

Release types

While it is possible to deploy Adobe Launch build when and how you see fit, it is a good idea to understand when the best time is to deploy sensitive changes to the website. This will minimise the impact of any issues.

Normal release

A normal release will usually contain one or more logic, configuration, and code changes. These changes are the most sensitive. While you would have done the necessary tests on the dev or stage instances, there is always a slim chance that things can go wrong.

To minimise the impact of any issues you should always deploy in the morning from Monday to Thursday. In the morning because usually this is where the traffic of your site will be low enough. You should avoid releasing on Friday as it is unlikely someone will monitor your changes over the weekend, and you run the risk to introduce an issue over the whole weekend.

Configuration changes

Usually, configuration changes are minimal and should only have changes related to data elements. Data elements will hold specific logic to return the configuration needed for a marketing pixel to fire correctly.

You should still apply same timeframes as for normal changes unless your campaign goes live later during the day or on a Friday.

Hotfix changes

There will be times where you tagging build simply breaks something due to your release or the platform release. It has not been caught during testing and every minute you wait costs money.

For hotfixes it is usually accepted to release whenever the fix is ready and tested, may it be day or night, weekday, or weekends.

Adobe Launch Coding Standards

Alexis Cazes — Tue, 21 Dec 2021 12:49:30 +0000

This post is part of a series about auto-tagging

Adobe Launch TMS allows you to use built in features to deploy tags on your website. In some instances, you will be required to write some JavaScript custom code as the tagging features are not enough to achieve your requirements.

By injecting JavaScript code directly on the website, there is always risks that your changes can bring a functionality or the whole website down.

Several best practices should be followed by your tagging team to minimize these risks.

JavaScript Style Guide

You should always first check inside your organisation if a JavaScript style guide has been defined. If there is one it is always a better choice to use your organization one than to use an external one.

If there is none then you can try to adopt one that is shared online. In most cases your team will not have enough skills or knowledge in JavaScript to define one from scratch. One safe choice is to use the one defined by Airbnb.

try/catch

It is acceptable for your code to fail, but it is never acceptable to break a functionality or the whole website. To prevent this, you should always wrap your custom code in Adobe Launch custom code editor between try/catch. You should always provide a meaningful and unique error message, which should allow you to easily troubleshoot your issue.

Make sure you document which name to give the error. We for example decided to only use e for our try/catch.

try {
    if (typeof event.details.test !== 'undefined') {
        return true;
    }

    return false;
} catch (e) {
    _satellite.logger.error('Failed in rule 123', e);
}

notice that Adobe Launch provids its own instance of logger. Ideally it should be used as the error will only be displayed if Adobe Launch debug mode is enabled.

Self-documenting code and minimal complexity

Self-documenting code is a best practice, where your code is written in a way that requires little to no comments. A rule of thumb is that it should take 30 seconds to have a good understanding of what your Adobe Launch tag does, otherwise it is poorly written or too complex.

There are a lot of articles that are about this subject so you should take some time to go over them and find the right balance for your team.

Bad

function generate(a, b) {
    return a + '-' + b;
}

var id = generate(a, b);

Good

function generateApplicationId(productName, randomNumber) {
    return productName + '-' + randomNumber;
}

var applicationId = generateApplicationId(productName, randomNumber);

Do not repeat yourself

DRY principle is all about creating reusable code and tags that can be reused in your Adobe Launch web property.

It is normal for your stakeholders to provide you the code snippet from the marketing provider to deploy on your website. The easy approach would be to create a rule in Adobe Launch to deploy this code snippet providing specific event and conditions are met. However, this will create a lot of code duplication on your side which will increase the size of your Adobe Launch js file and it will also be a nightmare to maintain.

In this situation you should always pause and analyse the code snippet provided to you. You can for example use a code comparison tool which should indicate what is the difference between them. In most instances it will be IDs related to your org and campaign. Now that you have isolated this, you can either create a Direct Call Rule to be called each time you want the specific marketing pixel to be fired or create a private extension for this marketing pixel. You can use data elements to generate the correct ids to be placed in the script.

Public extension

Adobe Launch has a concept of public and private extension. Public extension is usable by any Adobe Launch users/companies. Private extension is the one developed by your company and only available to your company.

I will strongly advise against using public extension. In my organization we had 2 instances where such public extensions broke the functionalities of a website. You should only trust extensions developed by Adobe itself, any others you should review their source if available. If no github repo is provided, remove the .min at the end of your Adobe Launch JavaScript library and you should see exactly what the public extension is all about. I have seen public extensions using eval function which is a security and performance risk.

You should instead write your own private extensions and publish them. Using private extension instead of DCR is all about DRY principle and maintainability. While a DCR will follow the DRY principle, it will be harder to maintain across multiple containers. With an extension you will always know which version you are using. The update process will be simpler as your can release your updated extension and publish the new version in Adobe Launch build.

By following the coding standards, you will simplify your tagging implementation and it will be easier to maintain over time. This will also show to stakeholders that while your team is not bound by governance, you still take the necessary precautions to assure the security and performance of the code you deploy on the websites.

Adobe Launch Tagging Standards

Alexis Cazes — Tue, 21 Dec 2021 12:48:41 +0000

This post is part of a series about auto-tagging

Tagging Standards will allow you to set up a set of rules for your tagging team members to follow. By following them we will ensure that the content of your Adobe Launch container is secure, maintainable, and reusable.

Naming Convention

As a member of the tagging team, a big part of your daily job involves working inside the Adobe Launch interface. Without proper naming, you will soon realize that it is very difficult to maintain over time.

Example of good naming convention:

use camelCase when possible. This is particularly useful for data elements and direct call rules. Try to avoid snake_case or PascalCase
never use a single character to describe the web property, rule, data element, or a build
never use trailing or leading underscores (except if it refers to_satellite object)
acronyms and initialisms should always be capitalized or all lowercase
inactive rules and data elements should be prepended by zzz so you can filter them out easily. You can apply same for the web properties that are disabled.
if a data element is linked to a specific type of configuration then make sure to add it in the name. i.e: instead of facebookEventName, use marketingFacebookEventName. This way you can easily filter on all marketing configurations to find what you need.
avoid using abbreviations, use self-documenting syntaxes. i.e: instead of fbEventName use facebookEventName

Web Property

Each Adobe Launch property should have a clear name. It should describe either the project or the platform on which the web property is deployed.
In most companies, the TMS will be shared between multiple sections of the business and there might be more than one tagging team using Adobe Launch. It is a good idea to add a descriptive part that relates to the business.
Also, consider using a descriptive state of the web property.

i.e: P - Project 1 - LIVE: in this example P refers to the personal section of the business, Project 1 refers to where the container is deployed, and LIVE indicates that the container has been published to production at least ones.
i.e: C - NSA - BUILD: in this example, C refers to the corporate section of the company, NSA to the code name for the platform New Simple Application (which is referred as NSA internally), and BUILD indicates that this web property was never published to production and has most likely not yet been tested.

Publishing Builds

Make sure to set a build name as informative as possible.
Avoid single words like "fixes" or "tweaks".
If your build is linked to an internal ticketing system like JIRA, make sure to add it in the build name, maybe between square brackets for syntax purposes.

i.e: Add Adobe Analytics for product 1 journey
i.e: [JIRA-1] Add facebook marketing pixel

Rules

The rules naming convention is important as it will save you time when you are debugging. I have seen Adobe Launch builds that used rule name as "Global", which means that it is impossible to understand, by just looking at the debug logs, what this rule does.

A good rule naming syntax would be:

Rule type -- Event type -- Web site location where it is deployed -- Actions -- Version

Sections	Detail
Rule type	EBR: event based rule PLR: page load rule (top, bottom, domloaded ...) DCR: direct call rule Multiple types of rule should be separated by a pipe
Event Type	PB: page bottom PT: page top WL: window load (onload event) DE Change: data element change CLICK: click event on a DOM element It will be up to you to set your own acronyms for each event type Multiple events should be separated by a pipe
Location	The syntax for Location should be as follow: `Brand - Page Name - Item interacted with` Each section can have more than one value, each value will be separated by a pipe
Actions	You should define your own acronyms for the action types you will deploy. Stick with the same acronyms across all of your web properties Examples: AA: Adobe Analytics AT: Adobe Target FB: Facebook pixels Custom: anything that is a custom code and does not fall inside any other action category type Multiple actions should be separated by a pipe

i.e: PLR -- PT -- Brand1 - Product1 checkout section -- AA|AT -- v1: in this example we can clearly see the intent of the rule where the rule is a page load rule loaded at page top for Brand1 during the checkout process of Product1. Adobe Analytics and Adobe Target code is loaded as part of this rule.

Events

The following syntax should be used:

Extension Name -- Event type -- conditions

i.e: Core -- Page Bottom
i.e: Core -- Click -- Call me back button

Conditions

The following syntax should be used:

Extension Name -- Condition type -- Evaluation

i.e: Core -- Value Comparison -- isValidDomainAndSubdomain = true
i.e: Core -- Value Comparison -- productName ~ ^.*premium$

Actions

The following syntax should be used:

Extension Name -- Action Type -- Details

i.e: Core -- Custom Code -- Facebook conversion pixel
i.e: Adobe Analytics -- Send Beacon -- s.tl

Data Elements and Direct Call Rules

Follow these syntax rules:

use camelCase
no single characters - self-documenting name
no trailing and leading underscores (except _satellite)
acronyms and initialisms should always be all capitalized, or all lowercase

i.e: Correct data element names pageName, productName, productCode etc...
marketingFacebookEventName is better than facebookEventName
i.e: Correct DCR names would be: loadFacebookCore

Do not repeat yourself principle

You should always take a step back when deploying third party code using your TMS. The marketing team is usually not technical. It will always provide you a big snippet of code to deploy via a rule to track their marketing campaign.

If you take a step back and analyse the code, you will notice that 99% of the code provided for each marketing campaign is identical and only one or two part of the code are custom IDs. At that moment you should apply the DRY principle and create reusable tags and data elements. Replace the IDs by custom code to call your data element that will return the correct ID.

It is also a good idea to transport this custom marketing pixel implementation into a private marketing extension for Adobe Launch. This way you can provide an easy and friendly interface for your colleague to use to deploy any marketing pixels. It also becomes easier to maintain as you will need to update the code version of the marketing pixels once by updating the extension.

Small builds

Try to avoid creating huge builds with a lot of changes. In most cases you can split your builds in smaller chunks. This will speed up the peer review and approval process and assure better quality.

As you follow these tagging standards you will see that overtime the quality of your tagging eco system will increase. As the quality increases, so will be your peer review process and your testing/debugging exercise. The complexity of your implementation should also decrease.