Migrating to the Adobe Experience Platform Web SDK

There has been a growing sense of excitement around the capabilities of Adobe’s new Experience Platform as more and more information becomes available. What has quickly become apparent is that there are a number of key areas to think about, ranging from data schema design and data governance through to identity management and activation channels. However, in this post I’m going to focus on the very beginning of the data supply chain, and more specifically, what steps are needed in order to migrate to the Web SDK.

#1 Design Overview

The requirements for the project are very simple — migrate to the Web SDK without impacting Analytics data collection or Target optimisation/personalisation activities.

The current status of the website is as follows:
i) it has a data layer and Adobe Launch implemented
ii) the Launch configuration includes:
- ECID Service
- Adobe Target
- Adobe Analytics
- Data Layer Manager

To successfully migrate to the Web SDK we will:
i) utilise the existing data layer and Launch property
ii) remove the ECID Service, Target & Analytics extensions
iii) configure the Web SDK extension
iv) implement the new alloy pre-hiding snippet

#2 Edge Configuration

There is a step by step guide here, which gives a comprehensive overview of the different options that are available, so I won’t go over all of the details again. The main thing to point out is that you need to create an Edge configuration, and it needs to include a few basic bits of information about the different solutions you are using, in order to get up and running.

Firstly, I need to add the Client Code used for my Target instance:

I also need to specify which report suite the analytics data should go to:

After saving the configuration, you will then get a view of the 3 different environments, which will look very familiar if you’ve used Launch previously. It’s at this point that you can go and change the report suite value at an environment level, so that your test environments don’t send to your prod report suite, for example.

#3 Web SDK Configuration

Now that the Edge configuration has been created, we can move on to the main task of translating the existing Launch setup into something that Platform can understand. After removing the ECID, Target & Analytics extensions, the first thing I need to do is configure the AEP Web SDK extension.

In the first part of the config section you have the option to rename the alloy method i.e. if you already have a method called alloy on your website and want to avoid conflicts. The default Edge Domain is edge.adobedc.net, however, you have the option to create a CNAME record, which I would expect a lot of customers to do.

The next step is to choose the Edge Configuration, which is why it’s important that you create the configuration before you start configuring the Web SDK extension.

Next up is Privacy and the default consent level that you want to set i.e. what should happen if a user has not previously submitted their consent choices. If the default is set to “Pending”, an additional “setConsent” call will have to be sent once the user opts in, so that the SDK is aware of the status change. See here for more details on handling consent.

There is also a small section on Identity, which includes a really important setting that relates to ECID migration. The Web SDK extension uses a new cookie to store the ECID (farewell to AMCV), so this setting enables compatibility between the new cookie and the old cookie for migration purposes. I can’t think of any reason to not have this enabled, unless you have just purchased Adobe Analytics and don’t have an existing implementation.

I haven’t called out every single setting in the Web SDK extension — there are others relating to topics like download and exit links — but hopefully this gives you a flavour of what is required.

#4 Data Schema

Now that the Web SDK configuration is complete, we’re almost ready to start thinking about how the rules & data elements in Launch will need to change. However, before we can do that we need to check that our data schema contains the relevant properties that we need.

Designing a comprehensive data schema is a lengthy topic, so I’m not going to go into too much detail here; however, if you’re using Adobe Analytics, for example, you need to ensure that all of the data layer variables that populate your reports also have a counterpart in the schema.

In the example above we’re using the pre-built Target ExperienceEvent mixin, which also includes all the core properties (e.g. device, environment), the ExperienceEvent commerce details mixin and a custom-built Loyalty Details mixin. This ensure that there is a schema counterpart for traffic variables like url & pageName, all of the ecommerce product/purchase variables, and customer loyalty information.

#5 XDM Object data element

We can now head back to the Launch configuration and start creating the data elements and rules that are required to send data to the Edge endpoint. As a reminder, there are now only two additional extensions installed alongside the Core extension. I should point out that the Data Layer Manager is purely included based on personal preference, as I find that it makes implementations far more straightforward, but you can achieve the same end result without it.

One of the things I really like about the configuration process is that a lot of the work is done with one data element, the XDM Object. When you choose the XDM Object type it will automatically retrieve the schema(s) that you have set up in Platform, which then means you’re left with the relatively straightforward task of mapping all the properties to relevant data elements.

To make things even more simple for your Analytics implementation, there is a growing list of properties that are automatically mapped to relevant variables/reports. For example, I have mapped the web.webPageDetails.name property, which will automatically populate the “Pages” report in Analytics, to my pageName data element.

If you’re not too familiar with Launch then you might be wondering where that pageName data element is coming from. As mentioned earlier, I’m using the Data Layer Manager extension, so my data element is populated based on the value that is assigned to page.name in my data layer.

You might also be wondering where page.name comes from — cue the final piece (and also the very beginning) of the data supply chain, which is the onsite data layer. As you can see below, I have a property called page.name, and it’s the value assigned to this variable that will ultimately populate the pageName data element.

One last thing to mention about the XDM mapping is that it’s also possible to specify that a single data element will provide the entire structure for a certain property. For example, instead of having to individually map endless properties to support all of the products that show on your PLP, you can just map the productListItems array to a single data element that provides all of this information.

#6 Launch rules

My previous setup included a global rule that set Analytics variables and sent a page view to Analytics, as well as separate rules for each page template i.e. a rule for my product details pages so that the product syntax is constructed correctly. It also included a separate rule which loads the Target library and then sends the page view request to Target.

Previously it made sense to have one rule that sent the Analytics page view, supported by other rules that contribute additional variables on appropriate pages; however, with the Web SDK, the Set Variables & Send Beacon concepts don’t exist, so with the “Send Event” action you’re just deciding which event type it is and which XDM object you want to include in the payload. Consequently, it’s likely you will end up with a similar template-based rule approach but each rule will also be responsible for sending the data.

The example above shows a “main” page view rule that covers generic pages. There’s not much configuration required here, as you’ve already done the hard work when you created the XDM Object, so you just need to choose the web.webpagedetails.pageViews event type. I want my Target activities to be delivered automatically on page load, so I’m also ticking the “Render visual personalization decisions” option.

Below is what the request payload looks like on the home page; it’s worth mentioning that the only values I have manually mapped in Launch are webPageDetails.name and _ecapacityemeaptrsd.loyalty.authenticatedId, all of the other variables are automatically generated by the SDK

To send the correct data on a product list page we will need to create a rule in Launch that is specific to that page template.

Any page templates that include product information will require the productListItems array. Whilst the structure of that array will be different on a PLP and a PDP, for example, the other thing to consider is that you’re using the correct event type. Below is a simple example of what the XDM Object might look like on a product list page.

As I mentioned earlier, certain items are mapped automatically, and in the case of product information this means every “name” property in the productListItems array will appear in the Products report in Analytics. Gotchas still exist such as the “Product View” metric automatically being incremented if you send Product data without specifying an event, so configuring the correct event type is very important.

It’s pretty straightforward to translate the example above into something that works in Launch; again, you’ve already done the hard work mapping productListItems in your XDM data element, so all you really need to do here is select commerce.productListViews from the event type dropdown.

#7 Processing Rules

The arrival of tag managers meant that the need for processing rules was reduced significantly, however, the Web SDK signals a somewhat unexpected return. Whilst the list of automatically mapped variables is growing, there are still plenty that won’t find their way into your Analytics reports without some additional configuration.

In the example above I have configured a processing rule that sets Product List View (event1) if the commerce.productListViews.value property is set. Using the Real-time reports feature in Analytics, I can quickly validate that the data is coming through as expected:

After the processing is complete I can also check the data in my report suite:

#8 Adobe Target

Depending on how you have implemented Launch, the pre-hiding snippet could be required in order to eliminate flicker, hence my point around “minimal IT involvement” in the introduction. Other than that, it’s quite likely that the only other action you need to take is to tick the “Render visual personalisation decisions” option in the rules that you create.

If you have that checkbox enabled and there is an activity set up on the page you are viewing, you will see an additional request that uses the “display” eventType.

I’m conscious that I’ve run through the steps at a fairly high level, and at a fast pace, but that was intentional because I really just want this post to give you an idea of what the end to end migration journey might look like. Rest assured, I’m planning on writing separate posts that will really dig into the detail of some of the key steps, in order to provide a better view of all the component parts.

What I hope has become clear from this post is that migrating to the Web SDK doesn’t mean that you need to have a conversation with your development team about completely re-writing the data layer. Having the ability to translate your existing data layer into an XDM structure entirely within the Launch UI is such an important feature.

Talking of features, there are still a lot of items being worked on in the Web SDK roadmap, which you can take a look at here. I think it’s going to be really interesting to see how the roadmap develops over the next 3–6 months, especially for some of the bigger components like Heartbeat Video and Native VEC support but also for Analytics implementation features that we’ve grown to love over the years like plugins.

From a personal point of view, I think it’s an incredibly exciting time to be involved in the design, implementation and day to day use of Adobe products. Developments like the Web SDK present a fantastic opportunity to learn new ways of doing things, as well as the exciting challenge of getting to grips with a whole new set of moving parts.