{"id":163372,"date":"2025-03-29T16:33:46","date_gmt":"2025-03-29T16:33:46","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/custom-event-listeners-for-gtm\/"},"modified":"2025-03-29T16:33:46","modified_gmt":"2025-03-29T16:33:46","slug":"custom-event-listeners-for-gtm","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=163372","title":{"rendered":"Custom Event Listeners For GTM"},"content":{"rendered":"


\n<\/p>\n

\n

(UPDATE 1 Oct 2014<\/strong> Due to a change in how macros work in Debug Mode, the {{generic event handler}} macro no longer works when testing in Debug Mode. That means that you\u2019ll have to test your custom listener in a live container (I know, ouch!). If you want to test in Debug Mode, you\u2019ll have to skip using the {{generic event handler}} as a macro, and instead copy the inner function into the Custom HTML Tag, give the function a name, and use that as the callback in addEventListener<\/code> or attachEvent<\/code>.<\/p>\n

Also, to preserve the \u2018gtm.\u2019 namespace for native GTM features only, I have changed the prefix of the custom event name from \u2018gtm.\u2019 to \u2018event.’)<\/p>\n

When the good folks at Mountain View introduced auto-event tracking<\/a> for Google Tag Manager<\/a>, a collective sigh was heard around the world (I\u2019m just slightly exaggerating).<\/p>\n

Finally, the true power of GTM was unleashed.<\/p>\n

With auto-event tracking, one of the more difficult aspects of web analytics, tracking user interactions beyond the page load, was greatly simplified.<\/p>\n

\n

<\/p>\n

\"Custom<\/p>\n

<\/a><\/p>\n<\/div>\n

However, as a species we are in a perpetual state of dissatisfaction.<\/p>\n

When we got the Click, the Link Click and the Form Submit, we wanted more. So then we got the History listener<\/a>. Again, we wanted more. And we got the Error listener<\/a>. And then we wanted more again.<\/p>\n

To satisfy this undying thirst for more listeners, the community has been very helpful. In fact, before you read on, I want you to familiarize yourself with Doug Hall\u2019s excellent post on extending GTM\u2019s auto-event listeners<\/a>. The following guide will expand upon the ideas put forth by Doug, while striving to approach the elegance of his prose and wisdom.<\/p>\n

I\u2019ve also written many posts on GTM\u2019s listeners. I\u2019ll link to them at the end of this article.<\/p>\n

What follows is a step-by-step guide to creating a generic listener for all the various events you want to capture that are not yet<\/em> captured by GTM\u2019s own listeners. Once GTM introduces a proprietary listener for whatever event you want to handle, it would be best to start using that.<\/p>\n


\n X<\/span><\/p>\n

\n
\n The Simmer Newsletter<\/strong>\n <\/p>\n

\n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n

<\/span><\/p>\n

The listener prototype<\/h2>\n

The prototype of the custom event listener will require two components:<\/p>\n

    \n
  1. \n

    A Custom HTML Tag for each listener type you want to activate (e.g. change<\/em>, blur<\/em>, copy<\/em>)<\/p>\n<\/li>\n

  2. \n

    A generic Custom JavaScript Macro, which returns the handler function that pushes the event into the dataLayer<\/p>\n<\/li>\n<\/ol>\n

    As you can see, it looks pretty simple. And it is. As long as you observe proper design patterns and best practices, these two components will get you far.<\/p>\n

    The generic event handler macro<\/h2>\n

    Let\u2019s start with the macro, since it\u2019s the truly generic component here.<\/p>\n

    The macro returns a function<\/em>, which serves as the handler for the listener you\u2019ll create in the next step. For this function to be as generic as possible, it will be agnostic as to what the event was. It will do this by accepting the Event object<\/a> as its parameter, and parsing that for all the data it needs.<\/p>\n

    Showing is easier than telling, so here\u2019s the code for you to copy-paste:<\/p>\n

    Macro Name<\/strong>: {{generic event handler}}
    Macro Type<\/strong>: Custom JavaScript<\/p>\n

    \n
    function<\/span>() {\n  return<\/span> function<\/span>(e) {\n    dataLayer.push({\n      'event'<\/span>: 'event.'<\/span>+e.type,\n      'gtm.element'<\/span>: e.target,\n      'gtm.elementClasses'<\/span>: e.target.className || ''<\/span>,\n      'gtm.elementId'<\/span>: e.target.id || ''<\/span>,\n      'gtm.elementTarget'<\/span>: e.target.target || ''<\/span>,\n      'gtm.elementUrl'<\/span>: e.target.href || e.target.action || ''<\/span>,\n      'gtm.originalEvent'<\/span>: e\n    });\n  }\n}\n<\/code><\/pre>\n<\/div>\n
    This, in my opinion, is a pretty close emulation of how GTM\u2019s listeners work. What\u2019s important is that the object pushed into dataLayer does its best to mimic the design pattern of GTM\u2019s own listeners.<\/p>\n
    Let\u2019s go over the code line-by-line.<\/p>\n
    return function(e) { ... }<\/code> is the wrapper. The point here is that this macro must return a function<\/em>, since the listener we\u2019ll create in the following chapter requires a function or object as a parameter. If the macro wouldn\u2019t return a function but rather run the code itself, you\u2019d be sending some weird empty events every time the listener tag is written to the page template.<\/p>\n
    dataLayer.push({ ... });<\/code> is where the magic happens. Here the triggered event is pushed into dataLayer by observing the design patterns of GTM\u2019s own listeners. Now, you can observe these patterns if you want, or you can use your own syntax. I\u2019m a big fan of symmetry, which is why I prefer to follow GTM\u2019s syntax. This might result in some conflicts if GTM introduces a similar event listener out-of-the-box, but in that case it would be a good idea to migrate to this proprietary listener anyway.<\/p>\n
    'gtm.element': e.target,<\/code> pushes the element the event occurred on into the dataLayer variable \u2018gtm.element\u2019. This is a design pattern, and if you look at your click listeners and link click listeners, a similar object is always found in those as well. The idea here is that you can then use your Data Layer Variable Macro to explore properties of this \u2018gtm.element\u2019 object if you want to dig deeper into the DOM.<\/p>\n
    'gtm.elementClasses': e.target.className || '',<\/code> pushes the class of the event target into the variable \u2018gtm.elementClasses\u2019. If there is no class on the HTML object, an empty string is pushed instead.<\/p>\n
    'gtm.elementId': e.target.id || '',<\/code> pushes the ID of the event target into the variable \u2018gtm.elementId\u2019. If there is no ID on the HTML object, an empty string is pushed instead.<\/p>\n
    'gtm.elementTarget': e.target.target || '',<\/code> pushes the target of the event target (sounds weird) into the variable \u2018gtm.elementTarget\u2019. If there is no target attribute on the HTML object, an empty string is pushed instead.<\/p>\n
    'gtm.elementUrl': e.target.href || e.target.action || '',<\/code> pushes either the href or the action attribute of the event target into the variable \u2018gtm.elementUrl\u2019. If there are no such attributes on the HTML object, an empty string is pushed instead.<\/p>\n
    'gtm.originalEvent': e<\/code> is my own addition to this design pattern. Every now and then you might want to access the original event, exposed by the listeners. With GTM\u2019s out-of-the-box listeners, this is currently not possible, since they only expose the e.target<\/code> property of this event object. However, especially if you want to do stuff like identify clicks created by code and not by the user, access to the event object is a must. I hope this will be a standard feature in GTM\u2019s own listeners as well.<\/p>\n
    So that\u2019s what the macro looks like. It\u2019s possible some of the patterns need more work, and nothing is stopping you from extending the number of variables that are pushed into the dataLayer. I consider these variables to be the minimum<\/em> set you\u2019ll need in order to provide enough information for your tags while still remaining economical and conscious of best practices.<\/p>\n
    The listener tag<\/h2>\n
    Now that we have our generic event handler, the next step is to create a tag which sets up the listener. The key here is recognizing just which listener you want to set up. Also, for symmetry\u2019s sake I will only show how to prime the event listener on the document<\/code> node, because that\u2019s the generic way AND the way GTM\u2019s own proprietary listeners work. If you want, you can attach the listeners to specific DOM nodes, which reduces the risk of propagation problems<\/a>, but as a solution it won\u2019t be as generic any more.<\/p>\n
    First, here\u2019s the listener code itself. Put this in a Custom HTML Tag, and add a firing rule which uses either {{event}} equals gtm.js<\/strong> if you\u2019re attaching the listener on the document<\/code> node, or {{event}} equals gtm.dom<\/strong> if you\u2019re listening on specific HTML elements.<\/p>\n
    \n
    script>\n  (function<\/span>() {\n    var<\/span> eventType = \"change\"<\/span>; \/\/ Modify this to reflect the event type you want to listen for\n<\/span>    if<\/span> (document<\/span>.addEventListener) { \n      document<\/span>.addEventListener(eventType, {{generic event handler}}, false<\/span>); \n    } else<\/span> if<\/span> (document<\/span>.attachEvent) { \n      document<\/span>.attachEvent('on'<\/span> + eventType, {{generic event handler}}); \n    }\n  })();\nscript<\/span>><\/code><\/pre>\n<\/div>\n
    Anyway, here\u2019s a list of some of the most popular event types:<\/p>\n
    On the first line, you specify just what type of event you want to listen for. For the full list of supported types, follow this link<\/a>. Remember, you can also dispatch and listen to your own custom events, which makes this solution even more flexible. Here\u2019s MDN\u2019s excellent guide on creating and triggering events<\/a>.<\/p>\n
    'event': 'event.'+e.type,<\/code> pushes a value into the \u2018event\u2019 data layer variable. It takes the type<\/code> property from the event object, which is a string representing what type of listener was fired, e.g. \u201cchange\u201d, \u201cblur\u201d, \u201ccopy\u201d. So if the event was of type change<\/em>, this push would actually look like: 'event': 'event.change'<\/code>. (By the way, remember E-Type<\/a>?)<\/p>\n