There\u2019s a new listener in town! It\u2019s a few days now since the Google Tag Manager<\/a> team unleashed the History Listener<\/strong>, and the time has come for me to tell you what this baby can do.<\/p>\n The History Listener is designed to be used on websites where content is loaded dynamically. Typically, these websites make heavy use of AJAX<\/a> (A<\/strong>synchronous J<\/strong>avaScript a<\/strong>nd X<\/strong>ML), which is designed for loading content in the background and serving it dynamically without having to reload the page.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Because I don\u2019t want to go too deep into how a dynamic website works, this tutorial should be pretty simple. The key is to understand what events trigger the History Listener, and how you can track your page views in a website without static URLs bound to static content.<\/p>\n \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 A site which loads content dynamically is usually incompatible with certain default browser events. For example, if you have a site which dynamically loads its content without any change in the URL of the page (nothing happens in the address bar), what do you think happens when a visitor navigates away from your site and then clicks the browser Back<\/strong> button? I can give you a hint, they won\u2019t see whatever dynamic state the page was in just before they left.<\/p>\n This is, of course, a problem for search engines<\/a> as well, since they want to index pages with unique URL addresses, which each return a static, unique piece of content. This is why URL fragments<\/strong> (AKA anchors AKA hashes) were introduced to solve the problems with browser history. If you loaded content clicking an \u201cAbout Us\u201d link, your URL would have looked like This fixed the problem with browser history, since now you could detect changes in the URL fragment and serve appropriate content again, even if the user used the Back button. However, this wasn\u2019t good enough for search engines or for Google Analytics, which have a hard time dealing with URL fragments.<\/p>\n Enter the hashbang<\/strong> (coolest name to be ever given to anything anywhere). The hashbang is a hash followed by an exclamation mark: #!<\/strong>. It\u2019s an old invention, having existed in UNIX systems to facilitate script loading. Google adopted it as a schema to signify an AJAX site with crawlable content. When search crawlers came across the hashbang sequence, they translated it to a proper URL query parameter (escaped_fragment=_the-original-fragment<\/em><\/strong>). A query parameter meant that the page could be crawled and indexed for search engine users to find.<\/p>\n However, the hashbang isn\u2019t the easiest solution to implement, it looks absolutely horrible<\/a>, and it\u2019s just not how you should treat your URLs<\/a>.<\/p>\n The final chapter of the story, and the most relevant one for the History Listener, is brought about by the HTML5 standard. HTML5 introduced the window.history<\/a><\/strong> API, which can be used to manually manipulate browser history when loading content dynamically. You can now manually push a state into the browser history, and when someone navigates with the browser\u2019s Back button to your page, you can look for stored states and load them in order, just like the default behavior of a static website.<\/p>\n The History Listener listens for changes in browser history. If it detects such a change event, it will tell you what happened, whether there\u2019s a state object stored in history, and if there was a URL fragment change involved. You can use this information to send virtual page views, prevent certain tags from firing again, serve dynamic tags, and basically anything that you\u2019d normally do when a page is loaded.<\/p>\n You set up the History Listener like you would any other listener<\/a>.<\/p>\n Create a new tag<\/p>\n<\/li>\n Name it wisely<\/p>\n<\/li>\n Set Tag Type to Event Listener > History Listener<\/strong><\/p>\n<\/li>\n Set firing rule to All pages ({{url}} matches regex .<\/strong>*)<\/p>\n<\/li>\n<\/ol>\n <\/p>\n <\/a><\/p>\n<\/div>\n And that\u2019s it. This will set your listener up on all pages to wait for the triggers that activate it.<\/p>\n You\u2019ll also notice that a bunch of new auto-event variables have been provided. You can use these to access properties of the history event change after the History Listener has fired. Read more about these in my Macro Guide<\/a>.<\/p>\n The History Listener will activate every time one of the following occurs:<\/p>\n Call to the window.history.pushState() method<\/strong><\/p>\n<\/li>\n Call to the window.history.replaceState() method<\/strong><\/p>\n<\/li>\n A popstate<\/strong> event is detected<\/p>\n<\/li>\n The URL fragment (hash) changes<\/p>\n<\/li>\n<\/ul>\n window.history.pushState()<\/strong> is used to add a state into the browser history stack. pushState()<\/strong> takes three arguments: a state object, a title, and a URL.<\/p>\n The state object is where you store details about the content, which you can use later to serve the same content to the returning visitor. The title is just a way to name the history entry, though it can be used with popstate<\/strong> to set the page title. The URL is what will appear in the address bar of your browser after the pushState()<\/strong> csll is completed. This is especially useful, because your site visitors can share this \u201cvirtual\u201d URL, which can be then used to serve the correct content to visitors arriving via this link.<\/p>\n window.history.replaceState()<\/strong> is pretty much the same as pushState(), except that it replaces the current history state with the new state.<\/p>\n popstate<\/strong> is what occurs every time the active history entry changes. For example, the browser\u2019s Back and Forward buttons trigger popstate<\/strong>. If the history entry which is activated upon popstate<\/strong> was created by pushState()<\/strong> or replaceState()<\/strong>, the popstate<\/strong> event will have the stored state object as a property. You can use this object to serve the same content to people navigating through browser history to your AJAX site.<\/p>\n Note!<\/strong> There are some differences as to how and when browsers send the popstate<\/strong>. Chrome and Safari, for example, fire a popstate<\/strong> with every page load (since that\u2019s when the active history entry changes), but Firefox doesn\u2019t. Firefox requires a history entry that was created by a pushState()<\/strong> or replaceState()<\/strong> call.<\/p>\n URL fragment changes<\/strong> are remnants of the hashbang era, but fragments are still widely used on websites. For example, if you have internal anchor links, you\u2019ll trigger a fragment change event every time the visitor jumps to an anchor on your page. In AJAX sites, you can listen for fragment change events, and use these to send a page view or fire a tag of your choosing.<\/p>\n When the History Listener is running, and any of the events described in the previous chapter occur, a gtm.historyChange<\/em> is pushed into the data layer. Most of the properties in this event can be accessed by the auto-event macros, but it\u2019s good to know what the data layer entry looks like.<\/p>\n Here\u2019s what your dataLayer object looks like after a pushState() event. Here, the state object I push is very simple. It contains just a single key-value pair, page: \u201cAbout Us\u201d<\/strong>.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Here\u2019s what you dataLayer looks like after a replaceState() event. The parameters are the same as in pushState(). Note that I fired replaceState() just after pushState(), so you\u2019ll see the previous state object stored in the gtm.oldHistoryState<\/strong> property!<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n Now, if I navigate away from the page and return with the browser Back button, a popstate<\/strong> event occurs with my state object neatly stored within:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n As you can see, the old state and the new state are the same, because I navigated away from the Contact page and arrived on the same page after clicking Back in my browser. When popstate occurs, I can look into the history state object and send the correct page view for the dynamic content. In this case, I can see that the visitor returned to the Contact page.<\/p>\n Finally, here\u2019s me navigating from one URL fragment to another:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n As you can see, I first went to the bottom of the page via URL fragment #bottom<\/strong>. This triggers a popstate<\/strong> event, with #bottom<\/strong> as gtm.newUrlFragment. After that, I clicked \u201cBack to top\u201d, which transported me to URL #backtotop<\/strong>, and this is reflected in the screenshot above.<\/p>\n I\u2019ll show a quick example, expanding the idea of navigating to the \u201cContact\u201d page, where the page details are stored in a state object, created using pushState()<\/strong>.<\/p>\n The premise is that when your visitor clicks a link to the \u201cContact\u201d page, the contents are loaded dynamically. To account for history changes, the pushState()<\/strong> method is called with something like:<\/p>\n This pushes a new entry into your browser history stack, with a single property within the state object. This property is the one we\u2019ll want to access in a popstate<\/strong> instance, i.e. when someone returns to the contact page via a history event (browser Back, for example).<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n <\/p>\n <\/a><\/p>\n<\/div>\n <\/p>\n <\/a><\/p>\n<\/div>\n And that\u2019s it. You can attach this sequence to your page view tag, for example, ensuring that the page view is sent every time someone navigates back to your Contact content via browser history (see below for how to make sure the page view properties are in order).<\/p>\n The firing rule is important. You\u2019re looking for a gtm.historyChange<\/strong> event. This is pushed into the data layer when the History Listener is triggered. After that, you\u2019ll want to make sure that the event was popstate<\/strong> (the macro in (2)), and that the page<\/strong> property of the new history state has value \u201cContact\u201d.<\/p>\n Now when you send a page view, the URL will be correctly contact.html (since you provide that in the pushState() call). However, your document title might be off, unless you explicitly set it in your AJAX logic. A nice way to send the page title is to use the Document Path setting in your page view tag, and populate it with the value of a Lookup Table macro, which in turn evaluates the page<\/strong> property again. Allow me to demonstrate:<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n That\u2019s your page view tag. In the Document Title field, you\u2019re retrieving the value from a Lookup Table macro, which I\u2019ve named {{ AJAX – Page Title }}<\/strong>.<\/p>\n <\/p>\n <\/a><\/p>\n<\/div>\n This sets the page title depending on the page<\/strong> property, pushed into the data layer when the history listener is fired. You could set a default value to the Lookup Table macro, but on the other hand, if it doesn\u2019t return a value, the tag will just send whatever is found in the document.title<\/strong> property.<\/p>\n Phew! This turned into a monster of a tutorial. But that\u2019s to be expected. Working with AJAX and dynamic content is not easy, as there are so many things to factor in. Not only are there usability and browser compatibility issues involved, you\u2019ll also need to take search engines into account<\/a>, and you\u2019ll need to understand how history events work.<\/p>\n As always, I highly recommend that you brush up on your JavaScript before you start working with the History Listener. There\u2019s no damage to be done, but you don\u2019t want to screw your tracking by not understanding how state objects work, for example. Also, it\u2019s very likely that you\u2019ll have to return to your AJAX setup to make sure that pushState() calls and replaceState() calls provide all the necessary data for you to use.<\/p>\n![\"AJAX](\"https:\/\/www.simoahava.com\/images\/2014\/03\/ajax-example.jpg#ZgotmplZ\")
<\/p>\n
\n X<\/span><\/p>\n
\n The Simmer Newsletter<\/strong>\n <\/p>\nBackground<\/h2>\n
https:\/\/www.simoahava.com\/main#aboutus<\/code>.<\/p>\nSet up the History Listener<\/h2>\n
\n
![\"The](\"https:\/\/www.simoahava.com\/images\/2014\/03\/history-listener.jpg#ZgotmplZ\")
<\/p>\nThe triggers<\/h2>\n
\n
{{event}} equals gtm.historyChange<\/h2>\n
![\"Data](\"https:\/\/www.simoahava.com\/images\/2014\/03\/pushstate.jpg#ZgotmplZ\")
<\/p>\n![\"Data](\"https:\/\/www.simoahava.com\/images\/2014\/03\/replacestate.jpg#ZgotmplZ\")
<\/p>\n![\"Data](\"https:\/\/www.simoahava.com\/images\/2014\/03\/popstate.jpg#ZgotmplZ\")
<\/p>\n![\"Data](\"https:\/\/www.simoahava.com\/images\/2014\/03\/fragmentchange.jpg#ZgotmplZ\")
<\/p>\nExample of use<\/h2>\n
var<\/span> page = {page:\"Contact\"<\/span>};\nhistory.pushState(page,'Contact'<\/span>,'contact.html'<\/span>);\n<\/code><\/pre>\n<\/div>\n![\"History](\"https:\/\/www.simoahava.com\/images\/2014\/03\/history-change-source.jpg#ZgotmplZ\")
<\/p>\n\n
![\"New](\"https:\/\/www.simoahava.com\/images\/2014\/03\/page-property.jpg#ZgotmplZ\")
<\/p>\n\n
![\"Rule](\"https:\/\/www.simoahava.com\/images\/2014\/03\/rule-for-history-change.jpg#ZgotmplZ\")
<\/p>\n![\"Page](\"https:\/\/www.simoahava.com\/images\/2014\/03\/page-view.jpg#ZgotmplZ\")
<\/p>\n![\"Lookup](\"https:\/\/www.simoahava.com\/images\/2014\/03\/lookup-table-ajax.jpg#ZgotmplZ\")
<\/p>\nConclusions<\/h2>\n