examples

The Rule Sandwich: now for the webSDK!

by

(Note: this was originally published March 2025 on the 33 sticks blog.)

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:

  1. 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:

  1. 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.
  2. 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 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 (in my experience, it only worked if the data element had a new name, otherwise it kept trying to reference the old ID) and going through each Update Variable Action and changing its 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”

Adobe’s Opt-In Service for Consent Management

by

This is cross-posted from the 33 Sticks blog.

Adobe’s Opt-In Service is a tool provided by Adobe to help decide which Adobe tools should or should not fire, based on the user’s consent preferences. It has some advantages I don’t see folks talk about much:

  1. It manages your Adobe tags (Analytics, ECID, Target) at a global level. If you’ve got it set up right, you don’t need to make any changes to your logic that sets variables and fires beacons (you don’t need a ton of conditions in your TMS)- any rule’s Analytics or Target actions will still run, but not set cookies or send info to Adobe.
  2. When your existing variable-and-beacon-setting logic runs while the user is opted out, Adobe queues that logic up, holding on to it just in case the user does opt in. Any Adobe logic can run, but no cookies are created and no beacons get fired until Adobe’s opt-in service says it’s ok.

This latter point is very important, because in an opt-in situation, frequently consent happens after the initial page landing – the page that has campaign and referrer information. If you miss tracking on that page altogether, you will lose that critical traffic source information. Some folks just re-trigger the page load rule, which (depending on how you do it) can mess up (or at bare minimum, add complexity) to your data layer or rule architecture. So I’m a big fan of this “queue” of unconsented data.

You can even experiment and see for yourself- this site has a globally-scoped s object, and an already-instantiated Visitor object. Open the developer console, keep an eye on your network tab, and put this in, to opt out of analytics tracking on my site:

adobe.optIn.deny('aa');//opt out analytics

Then run code that would usually fire a beacon:

s.pageName="messing up Jenn's Analytics data?" //you can tell me a joke here, if you want
s.t()

No beacon!

Now let’s pretend you’ve clicked a Cookie Banner and granted consent. Fire this in the console:

adobe.optIn.approve('aa');//opt in analytics

And watch the beacon from earlier appear! Isn’t that magical?

Side note: The variables sent in the beacon will reflect the state when time the beacon would have fired. I tested this- if I do this sequence:

adobe.optIn.denyAll()
s.prop15="firstValue"
s.t() //no beacon fires because consent was denied
s.prop15="secondValue"
adobe.optIn.approveAll() //now my beacon fires

…the beacon that fires will have prop15 set to “firstValue”- it reflects things at the time the beacon would have fired.

To re-iterate: if you have the ECID service set up correctly, it will still look like your Analytics/Target rules fire, but the cookies and beacons won’t happen until consent is granted.

How to Use within Adobe Launch*

Most of Adobe’s documentation assumes you’re using Adobe Launch*, and even then, leaves out some key bits. The Experience Cloud ID extension has what you need to get things set up, but is not the complete solution (you can skip this and go straight to the Update Preferences section below if you want the part that’s not particularly well documented). Let’s walk through it, end-to-end:

Opt-In Required

First, tell Launch when to require Opt-in.

If it’s just “yes” or “no”, then it’s simple enough. If you want to decide dynamically (based on region, for example), then you need to create a separate Data Element that returns true or false. For example:

if(_satellite.getVar("region")=="Georgia"){
     return false //Georgia doesn't care about consent. Yet.
}else{
     return true
}

To be honest, to me it’s always made more sense to just click the “yes” option, then further down, change up people’s default pre opt-in settings based on region.

Store Preferences

I’ll admit, I’ve never used these, but I think they’re self-explanatory enough: the ECID is offering to store the user’s consent settings for you. This seems convenient, but I’ve never seen a set up where the overall CMP solution doesn’t already store the consent preferences somewhere, usually in a way that is not Adobe-specific.

Previous Permissions/Pre Opt In Approvals:

The “Previous Permissions” and “Pre-Opt-In Approval” settings work very similarly, but “Pre-Opt-In Approval” is more of a global setting, and “Previous Permissions” is user-specific (and overwrites “Pre-Opt In Approval”). In other words: Pre-Opt-In Approval settings are used when we don’t have Previous Permissions for the user.

The key here is the format of the object, usually in a Custom Code Data Element, that Adobe is looking for:

{
   aam:true,
   aa:true,
   ecid:true,
   target:true
}

…where true/false for each category would be figured out dynamically based on the user. So your data element might have something like this:

var consent={}
if(_satellite.cookie.get("OptInInfoFromMyCMS").indexOf("0002")!=-1){
    consent.aa=true
    consent.target=true
    consent.ecid=true
}else{
    consent.aa=false
    consent.target=false
    consent.ecid=false
}
return consent

Important but often missed: updating preferences

All of the above is great for when the ECID extension first loads. But what about when there is a change in the user’s preferences? As far as I know, this can’t be done within the ECID extension interface, and it’s not particularly well documented… this is where you have to use some custom code which is kind of buried in the non-Launch optIn service documentation or directly in the Opt-In reference documentation. (I think we’re up to 4 different Adobe docs at this point?)

When your user’s preferences change, perhaps because they interacted with your banner, there are various objects on adobe.optIn that you can use:

adobe.optIn.approve(categories, shouldWaitForComplete)
adobe.optIn.deny(categories, shouldWaitForComplete)
adobe.optIn.approveAll():
adobe.optIn.denyAll():
adobe.optIn.complete(); //have adobe register your changes if you set shouldWaitForComplete to True

The “shouldWaitForComplete” bit is a true or false- if true, then Adobe won’t register your changes until you fire adobe.optIn.complete(). If false, or omitted, then Adobe will immediately recognize those changes.

So I might have a rule in Launch that fires when the user clicks “approve all” on my banner (or if I’m using oneTrust, within their OptanonWrapper function), with a custom code action that looks something like this:

adobe.optIn.approve('target',true);//opt in target 
adobe.optIn.approve('aa',true);//opt in analytics
adobe.optIn.approve('ecid',true);//opt in the visitor ID service
adobe.optIn.complete();

Which could also be accomplished like this:

adobe.optIn.approve(['target','aa','ecid']);

Or even just this (in my tests, this did not require adobe.optIn.complete()):

adobe.optIn.approveAll();

What if I’m Not Using Launch?

If you’re not using the Launch ECID extension, then the initial stuff- the stuff that WOULD be in the extension, as detailed above, is all handled when you instantiate the Visitor object. This is all covered Adobe’s Opt-In Service documentation, which I personally found a bit confusing, so I’ll go through it a bit here.

As far as I can tell, this bit from their documentation:

adobe.OptInCategories = {
    AAM: "aam",
    TARGET: "target",
    ANALYTICS: "aa",
    ECID: "ecid",

};

// FORMAT: Object<adobe.OptInCategories enum: boolean>
var preOptInApprovalsConfig = {};
preOptInApprovalsConfig[adobe.OptInCategories.ANALYTICS] = true;

// FORMAT: Object<adobe.OptInCategories enum: boolean>
// If you are storing the OptIn permissions on your side (in a cookie you manage or in a CMP),
// you have to provide those permissions through the previousPermissions config.
// previousPermissions will overwrite preOptInApprovals.
var previousPermissionsConfig = {};
previousPermissionsConfig[adobe.OptInCategories.AAM] = true;
previousPermissionsConfig[adobe.OptInCategories.ANALYTICS] = false;

Visitor.getInstance("YOUR_ORG_ID", {
    "doesOptInApply": true, // NOTE: This can be a function that evaluates to true or false.
    "preOptInApprovals": preOptInApprovalsConfig,
    "previousPermissions": previousPermissionsConfig,
    "isOptInStorageEnabled": true
});

Could be simplified down to this, if we skip the extra OptInCategory mapping and the preOptInApprovalsConfig and previousPermissionsConfig objects:

Visitor.getInstance("YOUR_ORG_ID", {
    "doesOptInApply": true, 
    "preOptInApprovals":{
         "aa":true,
     },
    "previousPermissions": {
         "aam":true,
         "aa":false,
     },
    "isOptInStorageEnabled": true
});

Literally, that’s it. That’s what that whole chunk of the code in the documentation is trying to get you to do.

Beyond that, updating preferences happens just like it would within Launch, as detailed above.

Side note- what’s up with adobe.OptInCategories?

I’m not sure why Adobe has that adobe.OptInCategories object in their docs. These two lines of code have the same effect, but one seems much more straightforward to me:

previousPermissionsConfig[adobe.OptInCategories.AAM] = true;
previousPermissionsConfig["aam"] = true;

The adobe.OptInCategories mapping is set by Adobe- despite it being in their code example, you don’t need to define it, it comes like this:

I’m guessing this was to make it so folks didn’t have to know that analytics is abbreviated as “aa”, but… if you find the extra layer doesn’t add much, you can bypass it entirely if you want.

Conclusion

Once I understood it, I came to really like how Adobe handles consent.

I am by no means considering myself an expert, or trying to make a comprehensive guide. But the documentation is lacking or spread out, so most of this took some trial and error to really understand, and I’m hoping my findings will prevent others from having to do that same trial and error. That said, I’d love to hear if folks have experienced something different, or have any best practices or gotchas they feel I left out.

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

The Adobe Launch “Rule Sandwich”

by

(Update- I have a version of this for the WebSDK now)

I’ve mentioned before how much I love that Launch* can “stack” all sorts of rules- by which I mean multiple rules of varying scopes can combine together into a single analytics beacon.

This means (using an example from that old post) I can have a global rule that sets my universal variables, a rule for search results, a rule for filters, a rule for null search results, and a rule that fires the beacon, all resulting in a single beacon where all the variables might be coming from a different rule. I call this a “Rule Sandwich”:

That particular example may be a bit overkill, but this ability to divide up your variables by scope can be key to a scaleable implementation.

As a programmer, there are some coding best practices we should all try to follow:

  • Don’t Repeat Yourself (DRY): If you can find a single place to set a variable, do it. Don’t set site section in every page that has a site section- set it in a global place that can dynamically set the right value from the data layer.
  • Keep It Simple, Stupid (KISS): Daisy-chaining Direct Call Rules can quickly complicate an implementation and introduce multiple points of failure. Huge Switch statements in code can make it hard to find specific dimensions or events.
  • Principal of Least Astonishment: People who encounter your setup shouldn’t have any surprises. If the next person who signs in to your Launch property says “oh, wow” or needs a “eureka” moment, you may have over-engineered things.

Following those principals, here’s the “Sandwich” set up I most like to use:

The bottom slice: Global Variables

My first rule sets my universal variables- things like site section, campaign, login state, user ID, etc. Stuff where I can say “if it exists in the data layer, I want it in my beacon”. It is set up to fire on all triggers that might end up in an analytics beacon. If you’re using the Adobe Client Data Layer extension and all your rules are triggered by your ACDL data layer, then this can be pretty simple, thanks for “Listen to All Events”:

But I’ve also had setups like this:

I add “#1” to the trigger name and rule name to indicate that these are triggered with a rule order of 1:

Which means for any given trigger**, this will be the first rule to fire. In this rule, I set any variables that can be applied globally- usually things like page name, site section, page type, language, etc.

**A note about sequencing: the order for rules only applies when rules share a common trigger. If you have a rule that fires on DOM Ready, and a rule that fires on a “page view” event in your data layer when DOM Ready occurs, even if they happen at the exact same time, Launch won’t compare their order to see which comes first. The rules would either both have to be triggered on DOM Ready, or both triggered on the “page view” event.

The Analytics extension does a great job of keeping everything in sequence. In other words, if I have a rule with an order of 1 that sets analytics variables I can be confident that a rule with the same trigger with an order of 50 will apply its analytics variables only after the first rule has finished. (However, Custom Code blocks will not wait for earlier-ordered custom code blocks from other rules to finish. If I have a rule with an order of 1 that runs some script in a custom code action, I can’t know for sure that script will have finished before code in a separate rule with an order of 50 happens.)

You might ask “Why don’t you use the Adobe Analytics Extension’s global variables?”

The problem with these is they only evaluate once, when the extension first kicks in on page load (go upvote my idea if you, too, want it to behave differently). So if you clear variables, they disappear and won’t come back until the next page load. And if you try to pass new values- maybe the language preference changed, or maybe you have a SPA and need to pass a new page name- the extension won’t pick those up.

Many folks use the doPlugins function for this purpose, because it fires on every beacon. There’s a few reasons I avoid this when I can:

  1. I try to keep my variables out of code as much as possible- the more transparency in the interface, the better.
  2. I try to keep doPlugins light. With default settings, it runs on every click, whether that click results in a beacon or not.
  3. doPlugins is the LAST thing to fire before a beacon is sent to Adobe, meaning any customization I’ve done in other rules might be overwritten.

Which brings me back to my #1 rule that fires on all of my common triggers. I set my global variables, and that’s it- no sending a beacon (yet).

The middle of the sandwich- the “fillings”

Next come all my sandwich fillings: the rules that set variables based on more specific scenarios. Any logic that needs to only fire under certain conditions go here. It’s where I set events, set any user-action-specific dimension, and hard code any values.

These rules might be triggered by a page view under certain conditions (like “pageType of article”), or based on a specific event or element interaction.

So I might have a rule that fires on page view if the page type is equal to “article”:

(In theory, I could set something like content.title in my global variables rule, because it will only set if the data layer currently has a value, but I’d rather keep all my blog stuff together and not make my global rule evaluate data elements unless they’re needed.)

I may also use these rules to customize/fix anything that had been set in my global variables. In an ideal world, data layers would be perfect and we’d never have to “fix” anything in Launch. But this isn’t that ideal world. My global variables might set the page type as “search results”, then later I realize our other search results page has a page type of “search”. Obviously, I should go to the devs and ask them to make it consistent. But in the meantime, I can use an “filling” rule to overwrite what was set in my global variables rule.

Not everything merits its own rule. If the scope only calls for a single extra event to be set, I could probably just do that in my global rule with a conditional JavaScript statement. But something like Purchase Confirmation, which has its own product string, purchaseID, etc… that makes sense as an “filling” rule. I try to find a balance between not having too many rules, and not having any single rule be super complicated.

The top slice: Send Beacon and Clear Vars

For any situation where many rules might all contribute to the same beacon- for example, page views- you can have the top piece of the sandwich as a rule with an order of 100, which fires the beacon and clears the variables.

If you have global page view variables- stuff you want on all page views but not necessarily all beacons- you could also put them here.

Note, splitting the “set variables” (our fillings) and the “send beacon” (our top slice) like this makes the most sense in a situation where you’ll have many potential rules all needing a beacon. Page Views is the best use case. Having a single separate “Send Beacon” rule makes it so if you have a few dozen page-specific Page Load rules, you don’t have to add the beacon and the clear vars action to all of them. It’s a time-saver, and a way to guarantee whatever the combination of filling rules, a single beacon will fire.

But in cases where there’s just one rule contributing to a beacon- something like a certain button click, for instance- then there isn’t much advantage to having a single “set variables” rule and a separate single “send beacon/clear vars” rule. You can combine your “fillings” and your “top slice” into a single rule, like this:

Clear Variables makes sure that variables (and particularly events) from earlier beacons won’t accidentally get attached to something they don’t belong to. Different folks handle “Clear Variables” differently. Some people set it at the beginning of rules (or sequences of rules). I find it easiest to always set it any time I fire a beacon, so I don’t have to worry about where in the sequence of things I’m clearing my variables.

Put It All Together (Examples)

Following this approach, my rules list might look like this:

(I tend to not put “#50” in the name of rules- it’s the defaultiest option; it can be assumed if no other order is specified. I also don’t specify “clear vars” in rule names anywhere- to me, it’s implied with any beacon being sent. See my post about rule naming conventions.)

On my search results page (which fires on a “page view” ACDL event where page type=”search results”), these rules would fire, in this order:

  • All Events | ACDL Any Event | Analytics: Set global vars #1
  • Search Result Views | ACDL Page View | Analytics: Set vars (#50)
  • All Page Views | ACDL Page View | Analytics: Send s.t, clear vars #100

On a Search Filter click, the following would fire:

  • All Events | ACDL Any Event | Analytics: Set global vars #1
  • Search Filters | ACDL Search Filter | Analytics: Set vars, send s.tl beacon (#50)

Conclusion

There are, of course, many “correct” ways to architect a TMS; this is just the one that has worked best for me across many organizations, particularly if they have a reliable event-driven data layer. I will say, it can get complicated if you’re using a wide variety of rule triggers, like page bottom, clicks on this but NOT clicks on that, form submission, element enters viewport, etc… the” “Top Slice”/Global Vars Rule’s list of triggers can get very unwieldy. And sadly, if you have a very Direct-Call-Rule-based implementation, since there is no out-of-the-box “fire on all direct calls”, you may find resorting to doPlugins is the simplest, most scaleable route. Your mileage may vary.

I’d love to hear what has worked for others!

No AI was used in this post. Images are good old-fashioned paid stock images.

*I’m still not going to call it “Adobe Experience Platform Data Collection Tags”.

Deploying Google Marketing Tags Asyncronously through DTM

by

I had posted previously about how to deploy marketing tags asynchronously through DTM, but Google Remarketing tags add an extra consideration: Google actually has a separate script to use if you want to deploy asynchronously. The idea is, you could reference the overall async script at the top of your page, then at any point later on, you would fire google_trackConversion to send your pixel. However, this is done slightly differently when you need your reference to that async script file to happen in the same code block as your pixel… you have to make sure the script has had a chance to load before you fire that trackConversion method, or you’ll get an error that “google_trackConversion is undefined”.

Below is an example of how I’ve done that in DTM.

//first, get the async google script, and make sure it has loaded
var dtmGOOGLE = document.createElement('SCRIPT');
var done = false;

dtmGOOGLE.setAttribute('src', '//www.googleadservices.com/pagead/conversion_async.js');
dtmGOOGLE.setAttribute('type','text/javascript');

document.body.appendChild(dtmGOOGLE);
dtmGOOGLE.onload = dtmGOOGLE.onreadystatechange = function () {
 if(!done && (!this.readyState || this.readyState === "loaded" || this.readyState === "complete")) {
 done = true;
 callback();

 // Handle memory leak in IE
 dtmGOOGLE.onload = dtmGOOGLE.onreadystatechange = null;
 document.body.removeChild(dtmGOOGLE);
 }
};

//then, create that pixel
function callback(){
 if(done){ 
 /* <![CDATA[ */
 window.google_trackConversion({
 google_conversion_id : 12345789,
 google_custom_params : window.google_tag_params,
 google_remarketing_only : true
 });
 //]]> 
 }
}

What the DTM “top down” approach means for your page performance

by

Any javascript framework, including all Tag Management Systems like DTM, have the potential to ADD more javascript weight to your page. But if you approach things the right way, this javascript weight  and its effect on your page performance can by mitigated by using DTM to optimize how your tools and tags are delivered. In a partner post, I’ll be talking about how to get the most out of DTM as far as Third Party Tags go, but I think one key concept is worth discussing explicitly.
You may have heard DTM be referred to as a “Top Down” TMS. For instance, this appears in some of the marketing slide decks:
topdown

While yes, it’s worth discussing this as a holistic approach to your digital analytics, it actually has a very real effect on how you set your rules up and how that affects page performance. That’s what I hope to discuss in this post.

In a different TMS, or even in DTM if I haven’t changed my mindset yet, I may be tempted to do something like this:

down-upRules

Where I have differing rules for different scopes as well as for different tags (we’re pretending here that “Wuggly” is a Third Party Marketing Pixel vendor).

DTM does what it can to defer code or make it non-blocking, but there are parts of the DTM library which will run as syncronous code on all pages. Some of that is because of the way the code needs to work- the Marketing Cloud ID service must run before the other Adobe tools; older Target mbox code versions need to run syncronously at top of page. But there is also the code in the library that serves as a map for when and how all of the deferred code should run. For instance, my library may include the following:

downUpCode

All of this logic exists to say “if the current pageType is “home page”, run this code non-sequentially”.  The name, conditions and event code for each rule run on each page as part of the overall library- these serve as a map for DTM to know which code must run, and which code it can ignore and not run.
You’ll notice the code for the two rules is completely identical, except for the rule name (in blue) and the source of the external script (in yellow). Most importantly, the conditions (in green) are identical. Whereas if they shared a rule, we might see the exact same thing as above accomplished with half as much code:

topDownCode

I now have ONE rule, which would be used for ALL logic that should run on the Home Page. The part of the library that runs on every page to check against conditions only has to check if the “pageType” is “home page” once, rather than twice. And DTM still loads the two scripts as separate non-sequential javascript. This doesn’t look like a major change, but when viewed across a whole implementation, where there may be dozens of rules, it can make a big difference in how many rules and conditions DTM must check on every page.

In the DTM interface, this would look like this:
topDownRules

If I want to know which rules contain my “Wuggly” codes, I can use the  “Tag Name” filter in the rules list, which will show me all rules that have a third party tag that includes “Wuggly”:
topDownFilter

This is filtering based on the Tag Name specified when you add the tag code:
topDownTagName

Using this approach, where your rules are based on their scope (or condition) and contain all logic- Analytics, Target, third party- that applies to that scope can not only lighten your library weight, but it can also keep your DTM implementation organized and scalable, but it may also require a change of mindset for how DTM is organized- if someone else needed to deploy a tag on Product Detail Pages, they wouldn’t need to create a rule, but rather, they could see a “Product Detail Page” rule already exists with the scope they need, and they need only add the third party tag.

There is one potential downside to consider, though- the approval and publication flow is based on Rules in their entirety. You can’t say “publish my changes to the analytics portion of this tool, but not to the third party tag section”. Still, if you are aware of this as you plan the publication of new features, this potential drawback rarely overrides the advantages.

How to approach Product Finding Methods

by

Product Finding Method (PFM) is a valuable custom report used by online retailers to tie Cart Adds and eventual Revenue to how users found the product. Unfortunately, these reports are often poorly configured or misunderstood. It is one of the best use cases for using the Merchandising setting on an eVar, but Merchandising, as a concept, is one of the more complicated topics in implementation.

Primer on Merchandising

In order to tie that PFM value to an individual product, and not the overall visit or visitor, we need to use Merchandising. And since we may not know the eventual product at the time that we know the finding method (for instance, if a user is using internal search, at the time we know they are searching, we don’t know what product they’ll eventually land on), we need to use Conversion Syntax- meaning we set it like a typical eVar (instead of in the products string) but have to configure at what point that eVar should be tied (or “bound”) to a product. Take the following user experience into consideration, where eVar5 is used for Product Finding Methods:

PFMflow

In the above, if I did NOT use Merchandising, my report might look like this, where External Campaign gets credit for everything up until it gets overwritten by Internal Search– at which point Internal Search gets credit for everything, including the entire Purchase event.

PFMnoMerchReportIf I DO use Merchandising, the External Campaign gets credit for whatever happens to the product it was bound to- in this case, the Blue Wug. Then Internal Search gets bound to the Red Wug, and gets credit for whatever happens to the Red Wug product:

PFMwMerchReport

We have to be very careful with the binding events (the event that tells Adobe to take whatever value we currently have floating around for that eVar and stick it to the current product), though- merchandising eVars won’t get credit for anything that happens if they are not bound to any product, or if that product isn’t currently present. For instance, in the example above, if you pulled in Internal Searches as a metric in that report, you’d see no PFMs were getting credit for the Internal Search event- even though eVar5 is set on the same page as our search event. That’s because that “Internal Search” value for eVar5 is waiting until a “binding event” to attach it to a product before it will get credit for any metrics, and the “External Campaign” value for eVar5 only gets visibility into things that happen to the product it’s bound to (Blue Wug). No products on the Internal Search page means Conversion-Syntax Merchandising eVars get no credit for the Search event.

How to Plan Your Product Finding Methods

To design your PFM solution, start by thinking of the different ways a client can add an item to their cart. We’ll call these “add to cart location” and give that its own eVar. Typical scenarios are:

  • product details page
  • quick view
  • from wishlist
  • from order history
  • recommendation/cross sell modules

Next, figure out all the ways a user could get to any of those above scenarios. These are Product Finding Methods and should get their own eVar. Typical PFMs include:

  • internal search
  • external site (referrerss and natural search)
  • external campaigns (that take the user directly to the PDP)
  • internal promotion (eg, homepage hero banner)
  • browse (naturally navigating through the menu or breadcrumbs)
  • cross-sell
  • recommendations
  • wishlist
  • order history 

You’ll notice some of your cart add locations may also be product finding methods- that’s ok. Note that Products Detail Page is NOT a PFM- the Product Details page is specific to the product, which is the thing being found not the thing doing the finding.

Both of these eVars will need to be set up for Merchandising (this is set in the Admin console>Report Suites>Edit Settings>Conversion>Conversion Variables). For the Add to Cart Location eVar, since we know the product at the time we know the add to cart location, you can use “product syntax”.

eVar4PFM

This is preferable because it leaves little room for error and has the easiest configuration. Let’s say I’ve set eVar4 to be my “Add to Cart location” eVar. At the time my user adds any item to their cart, I would set eVar4 (often, you can just set it to the current page’s page type):

s.products=";sku1;;;;eVar4=PDP"
s.events="scAdd"

But for Product Finding Method, you often don’t know what product the value for our eVar will eventually bind to, so we need to set it to conversion syntax, and we need to carefully consider which events should bind the current PFM value to the current product. Generally, Product View (ideally a custom event, not prodView) and Cart Add suffice as binding events.

eVar5pfm

DO NOT set to bind on ALL events, as many events happen on your site where your PFM eVar doesn’t have a desirable value.

Next, to implement, we need to figure out where to set each of our PFM values. If you’re using a tag management system like DTM, you can often just piggy back on existing rules for many of your finding methods, but others may need to live in global logic (like in your s_code). See below for a possible configuration.

internal search Set on internal search results page
external site Set in global logic- if no other PFM is present, and the user came from a domain other than your own
external campaigns Set in global logic, if s.campaign is set
internal promotion Set in global logic, if internal campaign eVar is set (or internal campaign query string parameter is present).
browse Set on all Product List Pages and Category pages
cross-sell Set when user clicks or clicks through on a cross-sell module
recommendations Set when user clicks or clicks through on a recommendation module
wishlist Set on Wish List page
order history Set on Order History page

Some folks manage PFM entirely in their s_code or in their (global DTM tool settings) based on whether other variables have been set (“if internal search term eVar has a value, set eVar5 to ‘internal search”‘). For instance, one client has something similar to this, in addition to setting their PFM eVar directly on certain pages (like their List Pages and Category pages, or certain microsites):

//easy way to get just the hostname of the referring site
   var a=document.createElement('a');
   a.href=document.referrer;
   s.refDomain=a.hostname;

if(!s.eVar5){ //if PFM not currently set on the page
   if(s.campaign){s.eVar5="campaign"} 
   else if(s.eVar10){s.eVar5="internal search"}
   else if(s.eVar23){s.eVar5="recommended product"} 
   else if(s.pageName=="My Account>Wishlist"){s.eVar5="my wishlist"}
   else if(document.referrer==""){s.eVar5="direct or bookmarked"}
   else if(s.refDomain.indexOf("mydomain.com")==-1){s.eVar5="external site"} 
 }
   else if(s.eVar15){s.eVar26="internal campaign"} 
}

Conclusion

Hopefully, this gives some ideas and examples for how to get valuable reporting on how users are finding and purchasing products on your site. I’d love to hear about potential scenarios or solutions I’ve missed!

How do I use DTM for a Single Page App?

by

The question of how to use DTM on Single Page Apps (SPAs) is a VERY hot item right now. By Single Page App, I’m referring to a full user flow contained on a single web page, so as to provide the user a more seamless experience. Often, these pages act like typical web pages, but they don’t always change URLs or load new resources. Many common web development technologies, such as Angular.js, Ember.js, and AJAX use SPA principles.

Unfortunately, there isn’t a single great answer for how to deploy DTM- it depends on many things. I’ll work through some of the options and the limitations to be aware of.

Suppressing Page View Beacons

Whatever method you take for tracking page views in a SPA, keep in mind most SPAs do have one true “page view” when the DOM first loads. If you are going strictly with the DCR or EBR route, you may need to suppress the initial page view beacon the Analytics tool will want to set by default. Otherwise, in the example below where the developers are firing a direct call rule on all page views, you’d get TWO beacons on the first page and 1 on all subsequent pages.

Picture1

Data Layer Considerations

You’ll need to make sure that whatever the sources of your Data Elements are (CSS selector, javascript objects, cookies…) have the correct values BEFORE your rule is triggered. I have an example site showing one way you might do this for a data layer (though you’ll need to look in the source code), but ultimately it’s going to depend on your site.

Variable Persistence

One last consideration is that once your Analytics object exists (as in, the “s” in “s.pageName”), variables set on it will continue to exist unless specifically overwritten. In most cases, you’d overwrite s.pageName with a new value so it isn’t a problem, but something like s.eVar5 may be set on the first beacon in your SPA, and not desired on subsequent beacons. You can use s.clearVars() to “refresh” your “s” object, but you have to make sure it fires at the right time- for example, after the beacon on Page A, but before DTM starts mapping Data Elements to variables for the beacon on Page B. How you do this will depend on the overall deployment method you choose.

Deployment Methods

1) Direct Call Rules

Perhaps the most straight-forward approach is to have developers fire a Direct Call Rule, like _satellite.track(“page view”) on every thing YOU consider a page view, whether it’s a fresh new DOM or not.

Advantages: Disadvantages: 
  • You have ultimate control over when a page view in considered a page view.
  • If you need to clear out variables between beacons (for instance, you set s.eVar5 in the first beacon in the SPA, and don’t want it in the second beacon), Direct Call Rules don’t provide a great place to use something like s.clearsVars(). There are some potential work-arounds, but none are ideal.
  • Developers need to add more DTM-specific code (satellite.track) to your pages.
  • Direct Call Rules don’t allow for extra conditions (like “fire THIS logic on pageA, and THAT logic on pageB”) in the interface.
  • Direct Call Rules don’t “stack”- if multiple rules have conditions that are met, multiple rules will fire.

2) pushState or hashChange

Many SPA frameworks, like Angular, use a certain flag to let the browser know the user is viewing a new “page”.

pushState

DTM can listen for this flag in an Event Based Rule using a pushState or hashChange condition.

ADVANTAGES: DISADVANTAGES: 
  • No additional code is needed- most SPA frameworks are already firing something DTM can listen to
  • It’s an Event Based Rule, which allows you to fire clearVars(), and set extra conditions
  • Because you are listening for an event set by the framework, you have less control over timing. Updating a data layer BEFORE the “pushState” event is detected would be critical.
  • Event Based Rules don’t “stack”- if multiple rules have conditions that are met, multiple rules will fire.

3) Custom Event EBR

Another option, which feels a bit like a blend of the first two options, is to use a Custom Event-based Event Based Rule (and no, that’s not a typo- it’s an EBR based on the JavaScript Concept of a Custom Event). It’s possible Developers are already using this Custom Event concept for their own code and purposes, and DTM can just listen for it… or you can have developers set one specific to our DTM needs by using something like my digitalData.userAction hack.

ADVANTAGES: DISADVANTAGES: 
  • You have a little more control over timing
  • It’s an Event Based Rule, which allows you to fire clearVars(), and set extra conditions
  • May require more developer work- similar level of effort as DCRs
  • Event Based Rules don’t “stack”- if multiple rules have conditions that are met, multiple rules will fire.

 4) (NEW OPTION!) “dataelementchanged” Event Based Rule

Just in the last few weeks, a new option emerged as part of the AEM Context Hub integration. This allows DTM to listen for changes to certain data elements- for instance, you could have a rule fire whenever the “pageName” has changed. My friends at 33 sticks have a great blog post about this already for more info.

ADVANTAGES: DISADVANTAGES: 
  • You have a little more control over timing
  • It’s an Event Based Rule, which allows you to fire clearVars(), and set extra conditions
  • Requires careful consideration of when the data layer changes/loads
  • Event Based Rules don’t “stack”- if multiple rules have conditions that are met, multiple rules will fire.

Setting up an Event-based Rule that be fired directly like a Direct Call Rule

by

Update:
As proud as I am of this solution/workaround, it may be far less needed now that you can use the dataelementchanged  condition to fire an Event Based Rule. Instead of using custom events, you can just have DTM listen for when your pageName Data Element has changed. 

The current limitations

If developers want to fire a DTM rule directly from their code (say, they want to make sure a beacon fires only after their data layer is ready), typically they would fire a Direct Call Rule, with its very specific syntax: _satellite.track(“rule string here”). There are, however, some limitations to this method.

Direct Call Rules:

  • Don’t allow for multiple conditions (you can’t say “if _satellite.track(“cart add”) is fired AND the current page has “/products” in the URL“)
  • Don’t allow for multiple arguments (you can’t pass _satellite.track(“cart add”,”sku1″) to attach the added SKU to the rule)
  • Don’t allow for firing s.clearVars() before your rule sets up your analytics variables (to clear out variables from previous beacons on the same DOM).
  • Require very specific syntax- they MUST be “_satellite.track()”

And unfortunately, both Direct Call Rules and Event-based rules don’t “stack”- if a certain condition triggers multiple similar rules, each rule will fire its own beacon. This is different from Page Load Rules, where if multiple rules have conditions being met by the current page, they all wrap nicely into a single page view beacon.

An alternative

To get around some (but maybe not all) of these limitations, I’ve been playing with another possible option, where we use the Custom Event conditions of an Event Based Rule to accomplish nearly the same thing. After getting it set up, I can fire something like this:

digitalData.userAction("cart add","sku1")

…to fire an Event-Based Rule in place of a Direct Call Rule. There are a few things I need to do in DTM to make this digitalData.userAction work.

Set Up the Logic

First, I have to set up the logic in a Page Load Rule- set to fire on DOMReady (no need for it to be sooner)- that will merely hold the following as a Sequential Javascript Third Party Tag:

//make sure digitalData is defined to prevent errors
if(typeof digitalData=="undefined"){
  digitalData={}
}

//create fake DOM item to bind the event to
var fakeDiv = document.createElement('div');
fakeDiv.setAttribute('id', "dtmHolder");
fakeDiv.setAttribute('height','1');
fakeDiv.setAttribute('width','1');
fakeDiv.setAttribute('style','display:none');
document.body.appendChild(fakeDiv);

//define custom event
digitalData.userAction=function(n,details){

 document.getElementById("dtmHolder").addEventListener("dtmEvent", function(e) {
    console.info("Event is: ", e);
  })

  // First create the event
  var dtmEvent = new CustomEvent(n, {
    detail:""
  });

  jQuery("#dtmHolder").attr("detail",details)
  
  // Trigger it!
  document.getElementById("dtmHolder").dispatchEvent(dtmEvent); 
}

(Update: note that this code should not run before the DOM is created- it will create an error if you try to run it at page top because you are trying to append something to a body that doesn’t exist yet).
Now, whenever a developer fires digitalData.userAction(“string here“), you can listen for that string as the Triggered Event Type in a Custom Event Event Based Rule. Obviously, you can alter the above code if you want a function named something other than digitalData.userAction.

Set Up an Event Based Rule

The rule will need to be bound to the CSs selector of the tiny fake div (“#dtmHolder”) we created for the custom event to bind to:

2016-04-20_12-38-12

You can create as many of these rules as you want, for whatever different strings you pass into digitalData.userAction()where the “triggered event type” reflects that string.

Pass Additional Info

If you want to pass a second argument ( e.g. digitalData.userAction(“cart add”,”sku1″)) I currently have that second argument  passing as a new attribute (“detail”) on the tiny invisible div, so you can access it off the “this” object directly in the rule:2016-04-20_12-41-52

You can give this a try at my ugly test site– open a developer console, turn on DTM debugging, and fire either digitalData.userAction(“cartAdd”,”sku123″) or digitalData.userAction(“pageView”) to see two example rules at work.

Run ClearVars

This opens the ability to run s.clearVars on s.t() beacons in cases where multiple beacons may be firing on a single DOM. (As a reminder, if you’re using the old DCR route, there are some hack-ish options for doing this- we call it daisy-chaining).

In an Event Based Rule, there IS a code block that runs before the Analytics tool, giving you a perfect opportunity to make sure you are starting with a ‘clean slate’ of variables: the Conditions Custom Code block. Just create a new Rule Condition with “custom” criteria, then put “s.clearVars()” in the code block, followed by “return true” (so that DTM doesn’t think some condition didn’t pass):

2016-04-20_12-52-49

You can also apply additional conditions, like “only fire this “cart add” rule on certain pages”, by adding more criteria under Rule Conditions.

Conclusion

I’m very open to suggestions and feedback on this- maybe we can crowdsource a better way, but for now, this seems to be a reasonable alternative to Direct Call Rules. Let me know what you think!