The Semantic Implementation

By | 12/02/2019

As implementation specialists, we need to think like product-builders. Our product is the implementation. This product has 2 end-users: stakeholders who use reports and teammates who help maintain the implementation. To get the most out of this article, we have to agree that reliable data is good and that you don’t want to spend your entire career jockeying the same implementation. You understand that becoming a dependency won’t grow your career. The solution is to be a product owner by pursuing a semantic implementation.

semantic
/səˈman(t)ik/

adjective

relating to meaning in language or logic.

A semantic implementation is one that is immediately meaningful to our teammates. Part of it is a good naming convention. The theme of a semantic implementation is using your expertise to simplify complex tracking while maintaining or improving delivery expectations. That means we are still answering all of our business questions. In fact, we’re going to ensure the data we send requires minimal transformation from our reporting analyst end-users. You’ll probably note a lot of parallels to Jan Exner’s No Custom Code Challenge.

Minimizing custom code is one tactic you can use to build a semantic implementation. I want to carry Jan’s torch a bit further and suggest we abstract ourselves from tactics. In a semantic implementation, we should be asking: “Would this make sense to a junior analyst?

The Junior Analyst

Let’s paint a picture of this junior analyst:

  • Entered the industry within the last few years
  • Has basic understanding of JavaScript, HTML, and CSS
  • Has basic understanding of tag management and analytics tools

This person isn’t writing much JavaScript at all. Maybe the junior analyst understands how to define a variable or gets the basics of if statements, but that’s about it. This is the person who will deploy a tag when you’re on vacation. This is the person who will take the reins from you while you pursue strategic initiatives and the person who will eventually pass it off to the next analyst once you’ve grown your team. Everything about your implementation must make sense to a junior analyst.

Rule Names

These are all REAL examples that I copied into a test property.

BAD

What the hell am I looking at? These aren’t descriptive, one is disabled (why is it still there?), some seem like duplicates, and based on capitalization it looks like 2 people who have never met are working on the same website.

bad rule names

On a side note, it’s remarkable how much time I waste accidentally going into disabled rules. I’d like to see the physical rule link or the entire line item change format if the rule is disabled (make it gray?). I don’t intuitively check to see if a rule is enabled if I’m in the zone.

GOOD

If you’re using GDPR rule conditions, I might add another parameter that delineates Targeting or Performance or other type of tracking.

good rule names

You’ll notice I no longer put the tag names in the rule name. It’s no longer necessary, as the Launch team implemented much more effective search features.

Data Element Names

BAD

We have one data element that reflects the JSON structure… which makes sense right NOW – but what if it changes? We have another that’s a camel-cased value. If I was a machine, I’d process this one real well. Then there’s User ID. I have no idea what to search for, I am terrified of any sort of data layer naming change, and I’m starting to make incorrect assumptions about where this data is sourced (data layer or…?). I find that with inconsistent naming you see a LOT of redundancy.

bad data elements

GOOD

Page data? Let’s look for Page. You get the idea.

good data elements

Custom Conditions

BAD

In some cases, we have a data layer driven Page Name on the desktop version of the site but not the mobile version. This is a little tricky because it forces you to work around sloppy development. While a Custom Code condition is the shortest path to your destination, it’s far from the best path. I call this the “screw it, I just want to get it done” method.

bad custom condition

Hardly 6 real lines of code. What’s wrong with this? For one, you’re setting variables in a custom condition. That’s not intuitive. Secondly, you’re creating several temporary variables that will likely be reused in other rules. Custom code conditions should be a LAST RESORT.

GOOD

Let’s start with a reusable asset.

mobile data element

Awesome. Now we know whether the site is mobile or desktop. The naming of this Data Element might be a little tough, but for analysis purposes we interpret user device as the type of site a person is viewing (mobile or desktop). In a perfect world, the site is responsive and doesn’t have this distinction. In that world, all of your data is also sourced from your data layer. Most of us don’t live in that world.

We now want to define our page name. Let’s start with the desktop page name because that’s already in our data layer:

desktop pagename data element

Next let’s build our mobile page name (Custom Code Data Element named Page | Name | Mobile):

mobile pagename data element

Finally, we’ll bring it all together into our last Data Element named Page | Name:

pagename data element code

Yes, it’s code. But we have comments, it’s centralized in a Data Element… and when the mobile development team gets off their ass, we can delete the Mobile/Desktop Data Elements and change this one to a JS Variable without having to update this value in a bunch of places.

So you know I’m not crazy, we went FROM:

  • 1 Rule
  • 0 Data Elements

TO:

  • 1 Rule
  • 4 Data Elements

It’s more work, but I have to ask myself what would make sense to a junior analyst. It would take much more time explaining why I have this mobile exception in the Custom Code of this rule (and maybe others) than it would if I said “Page | Name” will always be the page name. If you ever want to change the page name, change that Data Element. If you ever want to deploy something to only mobile users, reuse the “User | Device” Data Element. In theory, you could just use one page name Data Element, but the idea is to break things into smaller, more digestible pieces (and put them in logical places). There are always diminishing returns, of course.

Extension Configurations

BAD

Use of Adobe Analytics plugins should be minimized.

plugins

 

GOOD

There are extensions for depth and percentage of page viewed.

scroll and time

There is also an extension that forces values to lowercase.

In Summary

If you haven’t caught on, the idea behind the semantic implementation isn’t to do one specific thing. Its purpose is to design an implementation anyone can figure out. Beyond my above examples, there are also different places values can be set. For instance, if I want to set a eVar6, there are a number of ways I can do this:

  1. Extension Global Variables
  2. Extension Custom Code
  3. Custom Code Action
  4. Custom Code Condition
  5. Set Variables > Variables Section
  6. Set Variables > Custom Code

I’m proposing we try to only set these in Set Variables action. The value of these variables can be defined from all of these places AND ALSO Data Elements. I’m proposing we only define these values in Data Elements. Let’s build cool implementations, but let’s also be mindful that other people have to use them. Making your implementations predictable and intuitive takes time and effort, but it’s worth it when it’s time to pass the torch.

3 thoughts on “The Semantic Implementation

  1. Aaron Hardy

    Excellent article! Being empathetic to your co-workers is always good and provides a bonus for yourself when you come back to the implementation a year or two later.

    FYI, for the Custom Conditions example, one of the lookup table extensions can make it easy to implement the Page | Name data element instead of needing to resort to custom code.

    Reply
  2. Marisa

    Very good article, I totally agree!

    I do normally add the rule order to rule names, because Launch sorts the rules then by order, and second to see dependencies (e.g. 3 rules doing stuff, the fourth sending the analytics beacon).

    Reply

Leave a Reply

Your email address will not be published.