feat: skip tracking dynamically

Useful to ignore some lazyloaded pages or avoid
app-specific duplicate events with pageviewTemplate

Author: abruere

__tests__/lib/page.spec.js

@@ -67,3 +67,21 @@ it ('should set and track page with a VueRouter instance', () => {
   expect(window.ga).toBeCalledWith('set', 'page', '/')
   expect(window.ga).toBeCalledWith('send', 'pageview', '/')
 })
+
+it ('should skip tracking when page first argument is a falsy value', () => {
+  $vm.$ga.page(null)
+  $vm.$ga.page(false)
+  $vm.$ga.page(undefined)
+  // Google officially states that page path must begin with '/'
+  // https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#page
+  $vm.$ga.page('')
+
+  expect(window.ga).not.toHaveBeenCalled()
+  expect(window.ga).not.toHaveBeenCalled()
+
+  // Skip behavior must be explicit
+  $vm.$ga.page()
+
+  expect(window.ga).toHaveBeenCalled()
+  expect(window.ga).toHaveBeenCalled()
+})

docs/page-tracking.md

@@ -164,6 +164,10 @@ const router = new VueRouter({
 ```
 important: the route pageviewTemplate has always priority over the global one.
 
+`pageviewTemplate` can return a falsy value to skip tracking, which can be useful for specific needs:
+
+- `shouldRouterUpdate` documented below is more appropriate for tracking control based on routing, but is not enough when you need to disable initial tracking on some pages, since it only applies to navigation after initial page load.
+- `pageviewOnLoad: false` is global and can’t depend on current route.
 
 ## Avoid transforming route query object into querystring
 It is possible to avoid route query to be sent as querystring using the `transformQueryString` property
@@ -206,7 +210,7 @@ Vue.use(VueAnalytics, {
 })
 ```
 
-For other use cases it is also possible to use the `shouldRouterUpdate`, accessable in the plugin configuartion object, inside the `autoTracking` property.
+For other use cases it is also possible to use the `shouldRouterUpdate`, accessible in the plugin configuration object, inside the `autoTracking` property.
 The methods has the previous and current route as parameters and it needs to return a truthy or falsy value.
 
 ```js

src/lib/page.js

@@ -11,6 +11,11 @@ import {
 } from '../helpers'
 
 export default function page (...args) {
+  if (args.length && !args[0]) {
+    // allows to dynamically prevent tracking in pageviewTemplate proxy
+    return
+  }
+
   let route
 
   if (args.length && isRouter(args[0])) {