Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

Latest commit

 

History

History
115 lines (72 loc) · 6.04 KB

upgrading.md

File metadata and controls

115 lines (72 loc) · 6.04 KB
Raw

Upgrade Guide

From 1.x.x to 2.x.x

Breaking changes

  • Autotrack source code now uses ES2015 module syntax to enable tree shaking, which generates a smaller build. This may cause problems with some bundlers like Browserify that don't natively support this syntax.

cleanUrlTracker

  • When the cleanUrlTracker plugin is used, calls to tracker.get('page') will return the "cleaned" version of the page.

impressionTracker

pageVisibilityTracker

  • The change event action is no longer used; instead, events with a track action are sent after a page is transitioning out of the visible state to record the amount of time the page was visible.
  • The changeTemplate option has been removed since change events are no longer tracked.
  • The hiddenMetricIndex option has been removed since time in the hidden state is not a particularly useful metric.

New plugins

A maxScrollTracker plugin has been added. See its documentation page for usage details.

Updates and bug fixes

outboundFormTracker

  • A bug where the formSelector option was ignored has been fixed.

outboundLinkTracker

  • The use of target="_blank" was removed (for browsers that don't support the beacon transport mechanism) in favor of a manual redirect.

pageVisibilityTracker

  • A timeZone option has been added to help better detect session boundaries.

From 0.x.x to 1.x.x

Breaking changes

In versions prior to 1.0.0, you could include all autotrack functionality with the single command ga('require', 'autotrack'). This was a convenient shorthand that would individually require all other plugins. You can reference the original usage instructions to see an example.

In versions 1.0.0+, you can no longer require all sub-plugins with this one command. Instead, you have explicitly require each plugin you want to use and pass it its own configuration options (if necessary). This change was made to avoid users accidentally enabling plugin behavior they didn't want.

The follow example shows how to require all autotrack plugins in versions 1.0.0+ (note: the configuration options are omitted for simplicity):

<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXXX-Y', 'auto');

// Plugins must be required individually.
ga('require', 'cleanUrlTracker', {...});
ga('require', 'eventTracker', {...});
ga('require', 'impressionTracker', {...});
ga('require', 'mediaQueryTracker', {...});
ga('require', 'outboundFormTracker', {...});
ga('require', 'outboundLinkTracker', {...});
ga('require', 'pageVisibilityTracker', {...});
ga('require', 'socialWidgetTracker', {...});
ga('require', 'urlChangeTracker', {...});
// ...

ga('send', 'pageview');
</script>
<script async src="https://www.google-analytics.com/analytics.js"></script>
<script async src="path/to/autotrack.js"></script>

In all 1.x.x versions, requiring the autotrack plugin will do nothing but log a warning to the console. In version 2.0.0, this warning will go away, and calls to require autotrack may prevent subsequent commands from running.

mediaQueryTracker

  • The mediaQueryDefinitions option has been renamed to definitions.
  • The mediaQueryChangeTemplate option has been renamed to changeTemplate.
  • The mediaQueryChangeTimeout option has been renamed to changeTimeout.

socialTracker

  • The socialTracker plugin has been renamed to socialWidgetTracker and no longer supports declarative social interaction tracking (since that can now be handled entirely via the eventTracker plugin).

Updates and bug fixes

  • All plugins that send hits accept both fieldsObj and hitFilter options. These options can be used to set or change any valid analytics.js field prior to the hit being sent.
  • All plugins that send hits as a result of user interaction with a DOM element support setting field values declaratively.

eventTracker

  • Added support for declarative tracking of any DOM event, not just click events (e.g. submit, contextmenu, etc.)

outboundFormTracker

  • Added support for tracking forms within shadow DOM subtrees.
  • Added the ability to customize the selector used to identify forms.
  • Added a parseUrl utility function to the shouldTrackOutboundForm method to more easily identify or exclude outbound forms.

outboundLinkTracker

  • Added support for DOM events other than click (e.g. contextmenu, touchend, etc.)
  • Added support for tracking links within shadow DOM subtrees.
  • Added the ability to customize the selector used to identify links.
  • Added a parseUrl utility function to the shouldTrackOutboundLink method to more easily identify or exclude outbound links.

New plugins

The following new plugins have been added. See their individual documentation pages for usage details.