History change trigger

Tag Manager

A history change trigger fires a tag when a hash in the page URL changes or when the history object in the browser changes. It’s mostly used for tracking single-page applications (SPAs) where a regular tracking code fails to capture page reloads.

By default, the tag fires on all history changes, but you can adjust its conditions so that the tag fires for a certain page.

A history change trigger in Piwik PRO

Note: In this trigger we use the option: Wait 1 second before firing the tag. It helps to match page URLs with page titles in single-page applications.

  • When turned on: The tag will fire when the visitor stays on the page for at least 1 second. If they perform other events before this time, the events in between will be ignored and the last event will fire the tag.
  • When turned off: The tag will fire each time a hash or history object changes. All events will fire the tag.

We recommend that you turn it on because then your data will be more accurate.

You can choose from the following conditions:

  • Page URL: Fires a tag when a history object or a hash changes for the chosen page URL. For example, a visitor is on https://clearbank.com/product-tour and a history object or a hash changes.
  • Page path: Fires a tag when a history object or a hashtag changes for the chosen page path. For example, a visitor is on clearbank.com/ and a history object or a hash changes.
  • Page hostname: Fires a tag when a history object or a hashtag changes for the page with the chosen hostname. For example, a visitor is on any page with the clearbank.com hostname and a history object or a hash changes.
  • History source: Fires a tag when a pushState, replaceState, popState, or hashchange occurs.
  • History fragment: Fires a tag when a hash in the page URL meets a defined condition.
  • Old history fragment: Fires a tag when a previous hash in the page URL meets a defined condition.
  • History state: Fires a tag when a history state meets a defined condition.
  • Referrer: Fires a tag when a history object or a hash changes for the page to which a visitor was referred by the chosen referrer. For example, a visitor comes from https://clearbank.com/blog to any page and a history object or a hashtag changes.
  • External referrer: Fires a tag when a history object or a hash changes for the page to which a visitor was referred by the chosen external referrer. For example, a visitor comes from https://medium to any page on your website and a history object or a hashtag changes.
  • Campaign: Fires a tag when a history object or a hash changes on the website or page to which a visitor was referred by the chosen campaign (based on a utm_campaign parameter).
  • Traffic source: Fires a tag when a history object or a hash changes on the website or page to which a visitor came from the chosen traffic source: campaign, organic search, social, referral, direct.
  • Returning visitor: Fires a tag when a returning visitor is on the website or page and a history object or a hash changes (this mechanism is based on the Piwik PRO Tag Manager cookie).
  • Variables: Any added variable will show up on the list of conditions and you can use it to define trigger conditions.

Note: Multiplicity is not available for this trigger yet. We’ll add it in one of the future releases.

For more on a history object, read this article.

For more on a hash change, see this article.

Was this article helpful?

Technical support

If you still have some questions, visit our community.
There’s always someone ready to help!

Back to help center