A basic AEP Web SDK (Codename Alloy) implementation for Adobe Analytics

If you are taking care of an Adobe Experience Cloud implementation, there is practically no way for you to not hear about the new kid on the block: The Adobe Experience Platform Web SDK (also know as Alloy). It is the next big thing for how to implement solutions like Adobe Analytics, Target, Audience Manager, or the Experience Cloud ID Service. Instead of calling a plethora of different libraries and scripts, Web SDK is a single script that handles all functionality and calls trough a shared endpoint.

On the other hand, it’s not available to the public yet. If you want to try it out, you need to contact your Adobe Customer Success Manager and request to be included in the beta. That will give you access to the Edge Configuration in Launch and a stripped-down version of Adobe’s Experience Platform to manage the XDM. This already hints that there are a lot of different parts involved in getting a new implementation running.

After I recently switched jobs, getting beta access back has been my first order of business. Now that everything is in place, I gained some experience on how Adobe Analytics needs to be implemented that I want to share with you today. Specifically, we want to achieve those very basic things together today:

• Send our first event from Launch trough the AEP Edge to Analytics
• Track a Page View with a custom Page Name
• Track a custom, download, and exit link with correct names
• Set a custom dimension

A word of warning: If you want to get your hands dirty as well, please do read through this whole post first, as I will tell you my whole journey, including all the dead-ends and misconceptions that I had along the way.

Step 1: Creating our XDM event schema

First, we need to create the XDM schema that will hold our data. Think of this as a container that holds all the variables you can use for tracking later on. We need to do this in Experience Platform, so head there from your Experience Cloud homepage or the solutions menu:

Once you are in Platform, you want to go to Schemas (1) to create a new Schema (2) of the ExperienceEvent type (3):

That will give you a bare-bones schema with only a few fields. You could either create some custom fields or add some mixins, which are collections of commonly used sets of fields. To add mixins, click the Add button (1) and select the mixins you like. In my example, I’ve added the “Technical Details”, “Implementation Details”, “Data capture region for Experience Events”, “Web Details”, and “Adobe Analytics ExperienceEvent Full Extension” mixins (which is overkill for our use case, but we are just playing around for now anyways). Once you are done, name your schema (2) and save it. When we map those fields to Analytics dimensions, we need to know the path in the XDM, which the editor shows us once we select a field (3):

Here is where I went wrong when I created my first schema: I assumed that if I use the Adobe Analytics mixin, I could just use fields like “Prop 1” in Launch and later AEP would automatically map those to Analytics dimensions. But for some reason, that mapping does not happen! In contrast, only the variables mentioned on this page get mapped automatically. So while it may make your live a bit easier to use the mixin because of the naming, you will still need to map the variables in Analytics later on.

Step 2: Configuring the Edge Configuration in Launch

Next, we need to connect Launch to AEP. To do that, head over to Launch. You will notice that you have access to a new dropdown (1) where you can go to the Edge Configuration (2). Here we need to create a new configuration (3). Give it a fancy name (unlike mine) and create it:

By default, you will get three environments, one each for Dev, Staging, and Prod. Click on any environment to configure it:

First, we should rename our environment if needed (1). For our little project today, we just enable the Adobe Analytics switch (2) and fill in the Report Suite ID (3) we want to use:

Sadly, this field does not yet work as well as the Adobe Analytics extension in Launch. You need to know your ID, since the field does not connect to Analytics to fetch your existing Report Suites (yet). Once everything is set, save your environments and head back to the Client Side configuration in Launch.

Step 3: Client Side configuration in Launch

Now we are going to do the basic Launch configuration in the actual property we want to use. In there, go the Extensions (1) and search the Catalog (2) for the AEP Web SDK (3) Extension. Install and configure it:

Now we can give our JS object a custom name (1), which is very handy if we wanted to have multiple instances on the same page (2). Here, we select the Edge Configuration (3) we just created. Under identity (4) we can choose to reuse old ECID cookies and completely deactivate 3rd party Demdex cookies (nice!). Way at the bottom, we can enable click data collection (5) which is a bit similar to a combination of link tracking with Appmeasurement and Activity Map:

Next, we want to create a new Data Element to hold our data. For this, we name our element (1) and select the AEP Web SDK extension (2) which has the XDM Object (3) element type. Then we can choose our AEP Sandbox (4) and Schema (5). This will automatically load our schema to the interface as we know it from AEP. Notice the little icons beside the variables: They show if a variable is going to be auto-filled by the extension (6), if a value has been partially filled (7) or is completely empty (8). Once you click a variable (9) you can assign it a hardcoded value or reference another Data Element (10):

One thing I wish we had is a list of all possible values from all existing XDM mixins that the Web SDK extension can automatically fill out for us. If we wouldn’t have promiscuously added a lot of the mixins, some auto-filled details would be missing now! That’s just an unnecessary source for errors. Again, I also tried to assign values to the Adobe Analytics mixin, which ended up not being picked up by Analytics. That would also be an awesome addition to AEP and Analytics!

Almost done! Now we need to create a rule and add an Action from the AEP Web SDK Extension (1). We choose the “Send Event”-Action (2) and select our instance (3) from the dropdown. If you want, you can select an event type (4), but that does not affect Analytics as of yet. The only necessary field is the XDM Data Element (5) we just created:

Save it and publish the Library to your dev environment. Now let’s look at our data!

Step 4: Debugging our small implementation

Put your Launch tag on a local HTML page. Once your lib is published, you should see some events firing on the conditions you set. In your network requests, you should see the Edge Calls (1) with a JSON payload containing your events (2). This is a nice feature, since the Web SDK can send multiple events in one request for use cases like late consent optins. You can see that the extension auto-filled some device values (3) while taking the event type we selected (4). Lastly, we have the values we filled out by hand (5). Note how the event again matches our XDM structure:

Now let’s see what happens in Analytics. As a personal recommendation, add some basic metrics and dimensions to the legacy Real-Time report interface to see your events coming in. My configuration for now looks like this:

I only want to see the type of event coming in for now, so this is enough for debugging. And indeed, there are events coming in:

So now that we have events, let’s circle back to our initial list of goals. We already achieved the first one:

• Send our first events from Launch trough the Edge to Analytics
• Track a Page View with a custom PageName
• Track a custom, download, and exit link with correct names
• Set a custom dimension

Step 5: Tracking events and dimensions with Web SDK to Analytics

You might already know what the challenge with those next items on our list is: In the SDK’s actions, there is no distinction between a Link Click or Page View event like with the Analytics extension. That means that we need to tell Analytics which type of call we want to trigger by the variables we set. To discern between Page Views and Link Clicks, Analytics looks for a Link Name in the incoming event. If it exists, it registers a Link Click, and a Page View otherwise!

Now let’s track a Page View and set the Page Name. To do that, we need to reconfigure our XDM Data Element to set a field from the web fields (1) called “name” under webPageDetails (2) to a nice value (3). Make sure you don’t set the webInteraction fields (4), because Analytics would treat our event as a link click if we set a link type:

Save and publish your changes. Once you reload your test page, you should see the Page View event in our Real-Time report:

Success! Now we know how to track Page Views! Next, let’s set a Link Name and Type to track our first Custom Link Click. We edit our XDM one more time, going to the webInteraction object (1) and setting the name (2) to a good value (3). If we want to track different types of link events, we must set the type (4) to “other”, “download”, or “exit” respectively:

Depending on which Link Type you set, your events will then show up in the Real-Time report in the appropriate section for Custom Links (1), Download Links (2), or Exit Links (3):

Now to our last challenge: Setting a custom dimension! For our experiment, I will set Prop 1 to a value. Since I only want to use this value for Analytics, I will set it in the Analytics Extension’s field in our XDM Element:

Again, Analytics will ignore that value if we don’t tell it to pick it up explicitly! Up until now, it is just a context variable that is not being read. To do that, we must now create a Processing Rule in Analytics. In the Processing Rule Editor, create a new rule (1) to take the value of the XDM (2) path (in my case “_experience.analytics.customDimensions.props.prop1”) and prefix it with “a.x.” to a value like “a.x._experience.analytics.customDimensions.props.prop1”:

There are quite a lot of problems I see with this way of assigning values. First, the Processing Rules interface is ancient and not handling those long context data field names very well (see screenshot: there is no fast way to see which XDM field is being used). Second, handling 325 dimensions and 1000 events this way will get very messy. Even with an interface like Mobile Services this mapping is very tedious. But luckily, we have already been promised a new interface for processing rules. I’m excited to see that!

Back in the Real-Time interface, we can see the value now being properly evaluated:

There we have it! Our Prop 1 is now showing up correctly in the interface. Time for the wrap!

Conclusion

This was a nice Saturday-afternoon adventure for me. Figuring out all the intricacies of the Web SDK implementation for Analytics was fun, but the lack of documentation would be a real pain in any production environment. The effort to get up and running is quite significant today. But since Web SDK is in beta, here are some of my thoughts for future improvements:

• When creating a Schema in AEP, it would be great to have a “Web SDK” template, containing all the auto-populated fields from the SDK. Right now, the Data Element in Launch is the first time where we can know if a field gets auto-populated or not, which is a bit late. Update: Adobe has actually already delivered that!
• The fields from the Adobe Analytics mixin in the AEP Schema should automatically be picked up by Analytics. For a customer like me, who is mostly concerned about Analytics, this is a must to prevent double work. Update: This has also been delivered based on user feedback!
• As a creature comfort, it would be great if the Launch Edge Configuration would fetch the Report Suite IDs from Analytics, like the Analytics extension already does.
• Having a single, huge Data Element with the whole Schema is currently required, but very tedious. Things like value comparisons are practically impossible. Instead, I would like to have something like a “XDM wrapper” Element, that allows us to have multiple smaller Data Elements holding only part of the XDM and combine them with the wrapper.
• Since we can only put a single Data Element reference into any Web SDK Rule Action, we would need to have multiple XDM Elements for multiple Send Event actions (which could each have different Schemas). Managing that reliably sounds like a nightmare!
• Since we can select the event type in the Send Event action, it would be amazing if Analytics would respect the value we set there over the link type variable. That could help with the need for multiple rules and XDM Data Elements!
• At last, we direly need the new Processing Rules interface. Even something like Mobile Services would not be enough to handle the XDM level of complexity!

I know that Adobe is listening to feedback, so I would be happy to see those issues resolved in the future. The great thing is: It really works! And once the inconveniences are resolved I’m sure it will be awesome to use!

As always, let me know what you think of the AEP Web SDK and have a nice day!

Frequently asked questions

Frederik Werner

German Analyst and Data Scientist working in and writing about (Web) Analytics and Online Marketing Tech.

2021&2022 Adobe Analytics Champion

EMEA Adobe Analytics User Group Lead

www.frederikwerner.de/