Dynamic Tag Manager (DTM) Cheat Sheet

I’ve had a cheat sheet laying around for a while that includes a lot of helpful tips/tricks for Adobe’s Dynamic Tag Manager – formerly known as Satellite. If you would like to download a PDF of the old cheat sheet, click the link below (it’s almost 2 years old now). I won’t even make you tweet “Get the Advanced DTM Cheat Sheet from Portent Jimalytics!”

UPDATE: There is a new DTM Cheat Sheet! See the second link for the new one.
Satellite Cheat Sheet
 (OLD)
Dynamic Tag Manager Cheat Sheet v2 (OLD)
Dynamic Tag Manager Cheat Sheet v3 (NEW as of 3/27/17)

So this post will include updates, omissions, and other cool stuff you can do with DTM.


 

Creating and Using Variables

Basic %% Syntax

 

Example Google Analytics event using a variable.
Example Google Analytics event using a variable. Click to enlarge.

From an event rule to listen for a click on the following anchor element on jimalytics.com/index.html:

<a id=”someLink” title=”link” href=”/”><p class=”hi”>Hello</p></a>

“%this…%” uses the element that you have selected. In the current example, “this” is the <a> element:

%this.title% = link
%this.id% = someLink
%this.innerHTML% = <p>Hello</p>
%this.href% = /
%this.@text% = Hello

“%target…%” uses the child of the element that you have selected. In the current example, “target” is the <p> element:

%target.innerHTML% = Hello
%target.className% = hi

The %% syntax can also be used to get the document properties hostname and request URI (AKA document.location.pathname):

%URI% = /index.html
%hostname% = jimalytics.com

Additional Notes

  • Keep in mind that not all DOM elements are cross-browser compatible (like innerText)!
  • %this.@text% or %target.@text% is a DTM-specific variable and cannot be found in the DOM. Use this to grab just the text of any element (similar to $(this).text()).
  • It looks like there is also a special property for %this.@cleanText% which trims the text.
  • If you are using %target…% on an element with multiple children, it will use the last eligible value.
  • You can use anything that is available in the DOM for that element, which may include className, alt, href, id, innerHTML, title, src, etc. You can also use custom in-line properties, as well (i.e. <a foo=”bar” href=”/”><p>Hello</p></a>).

Data Elements

If you aren’t already aware, DTM has these things called Data Elements. They store nifty fields of data that you may use in rules on any page of your website. Did you know that you can manually set/get values via JavaScript within rules and custom JavaScript?

From the cheat sheet:

getVar gets the value of a set data element. While I think the %% syntax now works in the custom JavaScript section, I’ve gotten used to this method:

_satellite.getVar(‘data element name’);

Where there is a “get” there must also be a “set”. This script sets a data element:

_satellite.setVar(‘element name’, value);

This is what it looks like in action using the example in the first section:

<a id=”someLink” title=”link” href=”/”><p class=”hi”>Hello</p></a>

 

_satellite.setVar(‘link ID’, $(this).attr(“id”)); // sets the variable

_satellite.getVar(‘link ID’); // = “link”

Since some of you are visual learners, here’s the setVar in action:

Setting the variable in rule conditions.
Setting the variable in rule conditions.

 

Get the var via %% syntax in an event, prop, or evar. This is the same as using _satellite.getVar() if you're using custom JavaScript.
Get the var via %% syntax in an event, prop, or evar. This is the same as using _satellite.getVar() if you’re using custom JavaScript.

Additional Notes

  • setVar saves the data element on a page level scope – this is okay since you’ll typically only be manually setting these variables when you are referencing elements with $(this).
  • You can also use %% substitutions for these data elements within the UI. For the example above, we could have referenced the data element via %link ID%.
  • When you manually override a data element that exists and has a scope, it retains the scope of the element.

The _satellite Object

The DTM library reads like one big JSON object. If you open your console on a page that has Dynamic Tag Manager (Shift-Control-J), type _satellite. You should see a big object pop up that has a lot of data stored in it. This stores your rules, tools, data elements, publish date, build date… basically the kitchen sink. You can also mess around with the library, too! Here are some useful tricks you can use to get the most out of the tool:

Read a browser cookie

This is the same thing as setting a data element value as a cookie stored in your browser:

_satellite.readCookie(‘cookieName’);

Get user’s session/lifetime pageviews

This is similar to getting the pageview volume as a trigger condition from within rules. I found some use case for this at some point. Anyways, here it is:

_satellite.visitorSessionPagesViewed();

_satellite.visitorLifetimePagesViewed();

This may actually be deprecated. It isn’t active in my library, but that may just be because I don’t have any rules that use “Pages Viewed” as a criteria.

Get the date/time of publish and build

Sometimes when you make changes, you may be testing the code in production with an old library! Ew. Using the functions below will protect you from doing that.

buildDate gets the date/time that the library was physically updated (this is the important one):

_satellite.buildDate;

publishDate gets the date/time you pushed the “Publish” button:

_satellite.publishDate;

If you’re lazy like me and want to calculate how long it took between pushing “Publish” and actually updating the library, paste this (calculates value in minutes):

(Math.abs(new Date(_satellite.buildDate.replace(/-/g,’/’)) – new Date(_satellite.publishDate.replace(/-/g,’/’))))/1000/60;

Use the staging library in production

If you’re like me, you have 1 staging site and then you have your production site. Staging is never the same as production and sometimes things work in staging that might not work in production. Well now your problems are solved! Use this to enable your staging library:

localStorage.setItem(‘sdsat_stagingLibrary’, true);

Use this to disable your staging library:

localStorage.setItem(‘sdsat_stagingLibrary’, false);

Enable “Debug Mode”

Debug Mode in action.
Debug Mode in action.

Debug Mode tells you what rules are firing, what rules are not firing, and lets you know what events DTM is listening for. Here’s how you enable it:

_satellite.setDebug(true);

To disable… you guessed it:

_satellite.setDebug(false);

Hide your activity from DTM

If you want to browse your site incognito (let’s say you don’t want to trigger samples on your A/B test), simply use this:

localStorage.setItem(‘hide_activity’, true);

And for posterity – to disable:

localStorage.setItem(‘hide_activity’, false);

Use a cross-browser compatible console.log

So apparently console.log doesn’t work with some versions of IE. Fortunately, you can use notify which is compatible across all browsers:

_satellite.notify(‘text to display’, [importance ‘1-5’]);

It should work like this:

_satellite.notify(‘foo’, 1); // This should look like a normal console.log

_satellite.notify(‘bar’, 5); // This should be pretty big text

For whatever reason it isn’t working for me right now (I tried the number with and without quotes).

Anyways, that’s all I have for now! I would be happy to condense this information into a new cheat sheet PDF (or equivalent on another preferred platform). However, I’d like to sort out some of the loose ends like the pageview count and _satellite.notify. In the meantime, check out the cheat sheet I posted above for additional tips on RegEx, JavaScript and jQuery. Perhaps for the next installment we can go into some more complex implementation techniques.

47 thoughts on “Dynamic Tag Manager (DTM) Cheat Sheet

  1. You’re my hero! This is no longer official or made available from Adobe (liability/difficulty in keeping it updated), and I had really missed having it around. thanks so much for posting it.

    1. Sure thing Jenn! I am actually working on a new version that will have some of the updated functions and other methods :-)

  2. Hey. It seems like the syntax for _satellite.notify(‘foo’, ‘1’); is incorrect. The importance number shouldn’t have any quotes to work. For example _satellite.notify(‘foo’,1);

    1. Hey Sibel – I hope I’m not too late! What exactly are you trying to do? Is this something that cannot be detected via selectors?

  3. Hi there,
    I cannot seem to use %this% within any custom script. Could you please let me know how to use it?
    I am trying to have a Data Element which will return the clicked element so i get extract its attribute i.e. data-text.

    1. Hey Jerome – You can’t use the %% syntax within custom scripts. Instead, you will want to use something like jQuery(this) or $(this). However, you cannot use it in a Data Element. If you are setting a prop or eVar, you can simply use %this.data-text% to grab the attribute.

      1. Hi Jim,
        I tried out your suggestion of using %this.data-text%, but is not working. using the dtm debug i am seeing that it is just putting it as is without putting the value.

        1. Hey Raja – If all-else fails, add a custom condition in your rule that says something like _satellite.setVar(“Data Text”,jQuery(this).attr(“data-text”)); return true;

          Then in your prop/eVar/etc, you can use %Data Text% and it should grab that value. Let me know if that works.

  4. Hi Jim,
    Yea your suggested approached work, but wanted to try using the “this” variable. I was able to identify the correct syntax. %this.dataset.text% . thanks for your suggestion

    1. Ah, neat! I’ve never used that syntax before. It may actually be new! I’ll look it up and may need to update the cheat sheet. Thanks for the heads up, Raja!

  5. This is fantastic, thanks for publishing this information! Here are a few other tricks when referencing “this” in an event based rule:
    1. Use %this.@cleanText% to trim any whitespace, remove multibyte characters, or remove any newline characters.
    2. Use %this.getAttribute([attribute name])% to get any HTML attribute of the element. For example, if I have an HTML5 attribute named “data-linkname”, I can use this:
    %this.getAttribute(data-linkname)%
    Note that you will not add any quotes around the attribute name.

    1. This is awesome. Thanks, Adam! I’ll actually go in and make the change! Those are some pretty huge updates.

    2. Is there a way to leverage this.@cleanText in the custom JS sections? It keeps throwing an unexpected token error on the @.

      1. Hey Audrey! You will actually want to use _satellite.cleanText(someText) instead (obviously replace someText with whatever text you want cleaned up). The %this.@cleanText% will not work in Custom JavaScript sections, unfortunately.

        Edit: To be more specific, if you use jQuery you would type _satellite.cleanText($(this).text());

        1. Although jQuery is great, I really try to avoid using it in DTM so there is not a dependency on it (of course you can have DTM include it for you). You can use _satellite.text to pass any HTML object to it and it will return the text for you. Of course it’s not as easy or pretty as jQuery where you just pass a nice selector, but it is still a possibility.

          1. Good call out, Adam. Another useful tool to use to supplement jQuery is Sizzle – it’s much more efficient. For the life of me, I can’t remember if that’s baked into the DTM library – you may have to call it separately.

    1. Thanks Royston – that’s a good call-out. I’ll make a note in the post! Hopefully IE8 will be gone from this world in the foreseeable future.

  6. Hi Jim,
    I am using direct call rule, how can i get the below dynamic variable in DTM Rule js.

    var count = “#{VehicleSearchPagiBean.totalNoRec}”;

    1. Hey Dinesh – Tough to say. Are you trying to target an ID named “VehicleSearchPagiBean totalNoRec”?

      1. Thanks for your reply Jim, Currently i am trying to migrate the existing js methods for tagging from the jsp to DTM direct rules by copying it to Non-sequential code. But this particular value use the backing bean variable, how to get this value in direct rule js.

  7. Can you duplicate or copy a property inside DTM? Let’s say I have a property that I want to push to other/different analytics Report Suites and want to carry over all the same props and eVars. Do I need to recreate everything that was already created?

    1. Hey Tony – You’ll want to create a new property, select all the rules, and clone them over to your new property. You cannot copy a physical property, though.

  8. Glad I found your site, it’s been very helpful in getting to work moving all our old Site Catalyst tags into DTM. One thing I’ve not been able to figure out, this is an ecommerce site and we have a lot of events that track shopping cart actions, based on if the user is deleting items that are in stock, backordered, discounted, etc. I’m trying to figure out the easiest way to use DTM to send the list of applicable events to SC, but not sure how to do this. I know I could do it using Direct Call Rules, but that seems really cumbersome to set up a DC Rule for each event. How else would you do something like this where the list of events or other SC tags might not be known for a specific rule until at runtime?

    1. Actually I did figure this out, I had the right idea with what I was doing which was using the Custom Page Code for Adobe Analytics to set my list of events in s.events, but I wasn’t seeing any events showing up in my Debugger. What I forgot was using s.tl() to not trigger a page view, just setting s.events was not sufficient, I have to include s.linkTrackVars and s.linkTrackEvents. With those included, I’m getting what I was looking for.

  9. Great Cheat sheet. Thanks much.

    For an event based rule, I’m having trouble getting the referrer for a page. I’ve tried using jQuery and $, but get jQuery (or, $) is not defined, and I’ve tried window.document.referrer, all to no avail. Is the referrer available via a _satellite method, or some other script/function?

    1. Hey Michael – Glad you like it! Perhaps the jQuery library isn’t on the page? Have you tested the code in your console?

  10. am setting the _satellite.setVar(”dddd’,’true’) in one of the event based rule, when am trying to getVar(‘dddd’) its always undefined.

    MayI know if am doing anything wrong

    1. Are you using _satellite.getVar() within the same rule? When you use _satellite.setVar() in a rule it only sets it to the scope of that rule. If you want to set an element within a rule and reference it later (outside of the rule) you might want to consider using _satellite.setCookie() and _satellite.readCookie()

      1. Thank you Jim. Am setting the value in one of the event based rule and trying to retrieve the value in the Customize Page Code of the DTM property overview tab.

        I will try to use the set cookie.
        What am trying to achieve is one of the button click one particular event should fire.

        Thank you for your help.

  11. Hi, Jim! Thank you. Thank you. Thank you!!! This is by far the best resource I have found to date on DTM. I’m brand spanking new to all of the Adobe tools (having come from a Coremetrics background), and I’ve only been on the job here for two weeks. This will help greatly to fast track my progress. Best!

      1. Thanks, Jim!

        I have another quick (hopefully) question for you. Can you recommend a good resource for information/assistance on implementing AdWords Conversion Tags via DTM?

        Thanks!

        1. My pleasure! You should be able to copy/paste your conversion pixel in the 3rd Party JavaScript Tags section on a Page Load Rule assigned to your conversion page.

          1. Hi Jim,

            Thanks again for the response. I’m getting some issues in Google Tag Assistant and in AdWords with regard to the dynamic conversion value I’m trying to pass. I’m implementing on Dom Ready via asynchronous HTML. See below:

            Below is what I have currently implemented in DTM. The highlighted portion is the call I’m making to pull in the orderValue from the confirmation page (below that is an example of the underlying code from that page).

            Asynchronous HTML:

            /* */

            Underlying page source from where I’m capturing orderValue and feeding into a Data Element:

            analyticsData.orderNumber = ‘dc492ac47e1e4dec8e0667d6d837e7ef’;
            analyticsData.confirmationCartValue = ‘165.49’;
            analyticsData.confirmationCartNumberOfItems =’2′;
            analyticsData.state = ‘TX’;
            analyticsData.city = ‘SAN ANTONIO’;
            analyticsData.zip = ‘78201’;

            Test for orderValue in the console:

            _satellite.getVar(‘orderValue’)
            “165.49”

            Google Tag Assistant gives an error “Dynamic conversion value in wrong format” and that a closing script tag is missing, but I can’t see where there is an error.

            Sorry for the lengthy post. Hope this all makes sense. Any help or suggestions would be HUGELY appreciated…

  12. Is it possible to set data layer attributes after document is ready or loaded – meaning jQuery(document).ready function returns true? For it to work , we need to insert script tag having staellite js after data layer attributes are set. Can I get a sample code or a high level flow of code?
    Thans

  13. i want to implement a page load rule with condition for new visitor i.e. my rule should fire only if the user is new visitor but for me it is getting fired on every page refresh

  14. Hi
    We have implemented Page Load Rule in our search page but the problem is our price populates after page has been fully loaded through ajax so it is breaking my product syntax because i am not getting value when the page loads anybody has any solution for it please help me through it.

  15. Hi there,

    I just discovered “%this.pathname%” also works.
    Great for a shorter value in to the tracking values!

    Cheers,

    David

Leave a Reply

Your email address will not be published. Required fields are marked *