I’ve written previously about what I’ve found to be the most scaleable method of implementing analytics in Adobe Launch*, but that was for the old Analytics/appMeasurement way of doing things. If you’re using the webSDK, the Rule Sandwich is still an option, though it works slightly differently (and is a little less intuitive, IMO).

Before I tell you how, I highly recommend reading that previous Rule Sandwich post, but if not, at a high level, the idea behind the “rule sandwich” is to have:

1. one rule that fires everywhere, that sets all your global variables- things that follow the same logic everywhere, and belong on every (applicable) event, such as login state, site section, marketing campaign…

2. a set of rules specific to particular user actions (a product details page view, a form submission, etc) where you set variables that should only be set with that user action

3. potentially a third rule to fire the event/beacon off to Adobe.

The goal is to reduce redundancy and create something that scales. If page name is ALWAYS going to come from the same place in the data layer, there is no reason to configure that over and over. If I need to make an update to one variable, I don’t want to do it in a bunch of different rules.

The “Standard” webSDK Implementation: map your XDM Object

The “default” way (and for a long time, the only way) to setup your webSDK payload was to have a single “XDM Object” data element that mapped everything. Adobe’s documentation walks through how to do this. There is one big problem, though: some XDM fields (like anything you’d base a metric on) should only be set in certain situations- for example, I only want my Internal Search Input metric to increment “1” on the Internal Search Results page. If I had a single Data Element that handled all of my XDM set up, how do I tell it to only set _experience.analytics.event1to100.event5.value to “1” when the user is on a Search Results page? You could:

Have a data element for every metric, so you could use script to dynamically fill in that XDM field. If I have 50 events, that means I might have 50 data elements that each look something like this (or possibly more complicated depending on your conditions) :

if(_satellite.getVar("DDT: page type")=="search results"){
     return 1
}

…and then in your XDM Object Data Element, you’d do something like this for every one of your event fields:

2. You could create a separate XDM object for each situation. For example, you’d have a “Search Results” rule that pulls in your “Search Results” XDM Object Data Element, which has all your global variables, plus your internal-search-specific logic. Then you’d have another “Product Details Page” rule that pulls in your “Product Details Page” XDM Object Data Element, which also has all your global variables, and so forth.

3. You don’t set your situation-specific stuff in Launch at all, and instead use Data Prep to do something like this:

I really dislike all three of these options, though if I had to choose, I’d go with the first. Fortunately, Adobe provided another way: Update Variable.

A better option: Update Variable

To use Update Variable, you first need to create a webSDK Data Element of the type “Variable”:

This is a little unique, since it’s a Data Element that doesn’t really return something that you’d want to use, but rather just gives you abilities within your Rule Actions. The Data Element is mainly just to give you a place to specify the schema you want to follow.

Then you create rules with varying scopes, to “update the variable” as needed. At this point, you can think of it the same way you’d think of the Analytics “Set Variable” action (which can really help with migration, by the way- you can “migrate” one “Set Variables” at a time).

So, to make my rule sandwich, I’d start with a Global rule I want firing on all my events. The tricky part is finding covering all the different types of triggers that might fire tracking. If you’re using the ACDL extension, and not listening to any clicks or anything, then this is easy-peasy. But often it’ll end up being some combo of data layer events and clicks (and again, this is discussed in my previous Rule Sandwich post).

I’d give the trigger(s) a low “order” number (like 1, or 25… it’s all relative, just needs to be lower that my other rules). I’d create an action using the WebSDK’s “Update Variable” Action Type:

When I first open that “Update Variable” action, it will have me specify which variable I want to update, so I select the Data Element I just created. It will then create an XDM tree that matches your schema, very similar to an “XDM Object” Data Element. It even includes some helpful info, about how to tell what has been populated and how to clear out all or part of your variables as needed (which is important- we’ll get back to that later).

Since this is our global rule, I’d go through and set every field I have that should always fire, provided its data element has a value (login state, page name*, internal/external campaign tracking codes, etc).

*Note with Page Name and URL, you may not want to set that globally, particularly if this data is still bound for Adobe Analytics. Analytics bases whether or not it consider an event a “page view” (equivalent to an s.t() beacon) based on several factors, including the presence of URL or page name.

Then I’d create my situation-specific rules (my “sandwich fillings")- things that should only fire on certain pages or certain user actions. For instance, I might have a rule specific that fires on page load, only when my page type is ”Search Results”:

Then in my “update variables” action, I would set the fields for Search Results Term, Number of Search Results, and whatever metric I want to increment to indicate the user has made a search query:

Note, when I increment a metric, I should use the number, without quotation marks- it needs to be an integer, not a string. If the data is being fed only into Analytics then it doesn’t matter as much (it seems to handle strings and integers the same), but if the data is going into CJA, this will make it so much easier to turn it into a metric.

Finally, we need to actually fire events off to Adobe’s Edge. For page views, this is where the top slice of bread comes in: a rule, with order #100, with a webSDK “Send Event” action:

For non-page-views, I may just add that event to the existing “filling” rule. This lets me specify an event type that suits that user action. OR, I may create a different “top slice of bread”, if I have many rules all tracking something similar and I tire of adding a “Send Event” action to every single one of them. (Again, all of this is detailed in the original blog post- just swap “Set Variables” for “Update Variable”, and “Send Beacon” for “Send Event”.)

The final result should be an event payload that includes fields from your global rule and any rules where you updated your variable.

Gotchas

Clear variables

In the appMeasurement/Adobe Analytics world, we had issues with variable persistence and sometimes had to clear out our variables, and the webSDK is no different. If, for example, when my page loads, I “update my variable” to set my Search Results metric to "1” and fire an event, but then the user selects a search filter and I want to update the variable and fire an event again… that Search Results metric will still be “1” in my XDM variable. My “search filter” event payload will include my search results event, as well as any event I set earlier on that page, potentially duplicating metrics.

Fortunately, the “Update Variable” allows you to clear out previously-set fields. You can do this on a field-by-field basis, but with the Rule Sandwich setup, I find it easiest to just do it on my “bottom slice” global rule- select your top-level xdm object and check “Clear Existing Value”.

*(10 points if you spot the typo in the interface)*

Since you’re about to re-set all your important global variables, you don’t have to worry about erasing anything you wanted to hang around. If you are concerned about clearing something important, you can focus on clearing out the fields your metrics are based on, since those tend to be the ones we don’t want hanging around. For example, I can easily clear out most of my Adobe Analytics events by just focusing on the “event1to100” objects:

Copying between properties

We came across an interesting bug when using “Update Variable” when we tried to copy the whole set up from one Launch Property to another. We copied the XDM Variable Data Element and every rule that used it. Both properties followed the same schema and used the same datastreams, so it felt like a simple lift-and-shift. In the interface, everything looked great… but nothing worked. I was just helping out (it wasn’t my client) so I didn’t have access to the Launch properties in question, so I had to resort to troubleshooting in the code… which ended up being a good thing, because only there could I have seen the “Update Variable” action doesn’t reference the XDM Variable Data Element name, but rather, some internal ID, and that internal ID seemed to be copied from the original property.

The data element itself had one ID:

But the code for the Rule with the “Update Variables” action seemed to be referencing something else altogether:

Whereas the original property (which still worked) had the same ID (the one ending “4d3d”) in both of those spots. So our new property’s Update Variables actions were seemingly trying to reference the ID of the XDM Variable Data Element from our original property.

In my testing on my own properties, I could see that it should be as simple as giving your new property’s XDM Variable Data Element a slightly different name (this might not be strictly necessarily, but makes things less confusing) and going through each Update Variable Action and changing it’s variable to your new property’s newly-renamed Data Element. In my testing, at least, I did NOT lose the mappings I had worked so hard on when I changed my variable (hooray). It is annoying to have to do this in all your Update Variable actions, but better than starting from scratch. Make sure you also update the variable reference in your “Send Event” actions.

(Since I wasn’t technically on the account in question, I didn’t submit this as a bug to client care and I don’t know if anyone else has, but someone probably should.)

What works for you?

This is a method that has worked well for me, but (as any honest agency/consultant should tell you at this point)… we’re all still figuring this webSDK/XDM/CJA stuff out as we go. Unlike appMeasurement (and H code before it), I don’t have nearly 20 years of experience to tell you all the gotchas and to be able to say which methods will withstand the test of time. I have been on alphas/betas/POCs for the webSDK since 2019, but I only have a few XDM projects where I have been able to look back a year or two later and say “that worked well” or “I wish I had done something different”.

I’m grateful for consultants from other agencies (Adswerve and Slalom, in particular) not to mention MANY individual practitioners that have helped me puzzle some of this out. We all benefit from knowledge-sharing at this point, and one of my favorite things about this industry is how much folks generally care more about learning and sharing than they care about “competition”.

I’ll update this post if I figure anything out that’s relevant, and hope folks will reach out to me if they discover something that works better, or some other gotcha folks should be aware of.

*Still not calling it “Adobe Experience Platform Data Collection Tags”

The Rule Sandwich: now for the webSDK!