govuk_frontend_toolkit 7.2.0 → 7.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 538b9de6aaf9bd4fa8ec41041f55e19fc38bc25716f2684efde95b3eb5a0e3b9
-  data.tar.gz: 48c37a0f38db00cef1d3472610d5890bc0f7c70938d8b84f9adb01e6ee633ee0
+  metadata.gz: 0334902cdeefff962323abe904470c7558848f31bda9660316d85abf05e26d34
+  data.tar.gz: f69772e14fcbbbd38c6a5fecdc627618c990d481f6a818b8bba157d231b69a73
 SHA512:
-  metadata.gz: a4219bbd88e18c1bd0815f4bb89c38e01723ca3887c6ea1016673f69c3eded8818254053992659f0a0d5ad86825aedbeee190acb901c2a487b5cf9a78608a99a
-  data.tar.gz: 0d6bbce22e7e53064c9d01762f725958827bd68a2fec32c223aefb3d80d32c0fe596b4991e658be4f1861cb1a60e6351dedae60d3b075456719a5de622545d6e
+  metadata.gz: 57596cc95ffa5ec4c46b0e020cefde1007f2c2d074707e53b6ed3a221e5807e13c040f62289fc89fc561d5e56f758b6279e56f685f839a46149eb2eae1f12425
+  data.tar.gz: 608f7fa34a8f4723b883b564d401f52a3c9afca816303c574f7f0ca4574c458d0d9b32e243fa6828e5840ab403069275ed405d6a564efde0532fda50b2adf919

data/app/assets/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 7.3.0
+
+- Strip PII from all arguments passed to GA.  Emails are stripped by default, postcodes can also be stripped if configured to do so: ([PR #435](https://github.com/alphagov/govuk_frontend_toolkit/pull/435)).
+- Update sass and govuk-lint dependencies: ([PR #444](https://github.com/alphagov/govuk_frontend_toolkit/pull/444)).
+
 # 7.2.0
 
 - Add custom dimension on TrackEvent to duplicate the url information that we normally send on a the `event action`. This will be used to join up with a scheduled custom upload called "External Link Status". We can only join uploads on custom dimensions, not on `event actions`, where we normally add the url info. ([PR #436](alphagov/govuk_frontend_toolkit#436) and [PR #439](alphagov/govuk_frontend_toolkit#439))

data/app/assets/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
-gem 'sass', '3.4.15'
-gem 'govuk-lint', '0.7.0'
+gem 'sass', '3.5.5'
+gem 'govuk-lint', '3.6.0'

data/app/assets/VERSION.txt

@@ -1 +1 @@
-7.2.0
+7.3.0

data/app/assets/docs/analytics.md

@@ -7,6 +7,7 @@ The toolkit provides an abstraction around analytics to make tracking pageviews,
 * a generic Analytics wrapper that allows multiple trackers to be configured
 * sensible defaults such as anonymising IPs
 * data coercion into the format required by Google Analytics (eg a custom dimension’s value must be a string)
+* stripping of PII from data sent to the tracker (strips email by default, can be configured to also strip UK postcodes)
 
 ## Create an analytics tracker
 
@@ -216,3 +217,35 @@ plugin uses Google Analytics’ `transport: beacon` method so that events are tr
 Category | Action | Label
 ---------|--------|-------
 Mailto Link Clicked | mailto:name@email.com | Link text
+
+### Stripping Personally Identifiable Information (PII)
+
+The tracker will strip any PII it detects from all arguments sent to the
+tracker.  If a PII is detected in the arguments it is replaced with a
+placeholder value of `[<type of PII removed>]`; for example: `[email]` if an
+email address was removed, or `[postcode]` if a postcode was removed.
+
+We have to parse all arguments which means that if you don't pass a path to
+`trackPageView` to track the current page we have to extract the current page
+and parse it, turning all `trackPageView` calls into ones with a path argument.
+We use `window.location.href.split('#')[0]` as the default path when one is
+not provided.  The original behaviour would have been to ignore the anchor
+part of the URL anyway so this doesn't change the behaviour other than to make
+the path explicit.
+
+By default we strip email addresses, but it can also be configured to strip
+postcodes too.  Postcodes are off by default because they're more likely to
+cause false positives.  If you know you are likely to include postcodes in
+the data you send to the tracker you can configure to strip postcodes at
+initialize time as follows:
+
+```js
+  GOVUK.analytics = new GOVUK.Analytics({
+    universalId: 'UA-XXXXXXXX-X',
+    cookieDomain: cookieDomain,
+    stripPostcodePII: true
+  });
+````
+
+Any value other than the JS literal `true` for `stripPostcodePII` will leave
+the analytics module configured not to strip postcodes.

data/app/assets/docs/javascript.md

@@ -286,7 +286,7 @@ Links styled to look like buttons lack button behaviour. This script will allow
 
 ### Usage
 
-By default, this behaviour will only be applied to links with a role of button.
+This behaviour will be applied to elements with a role of button.
 
 ```html
 <a class="button" role="button">A button</a>
@@ -296,23 +296,6 @@ By default, this behaviour will only be applied to links with a role of button.
 GOVUK.shimLinksWithButtonRole.init()
 ```
 
-If you need to override the elements this is applied to then you can do that by passing in a custom selector to the initialiser:
-
-```javascript
-GOVUK.shimLinksWithButtonRole.init({
-  selector: '.my-class'
-})
-```
-
-It’s also possible to define more or different keycodes to activate against:
-
-```javascript
-// activate when the user presses space or ‘r’
-GOVUK.shimLinksWithButtonRole.init({
-  keycodes: [32, 114]
-});
-```
-
 ## Show/Hide content
 
 Script to support show/hide content, toggled by radio buttons and checkboxes. This allows for progressive disclosure of question and answer forms based on selected values:

data/app/assets/javascripts/govuk/analytics/analytics.js

@@ -2,11 +2,20 @@
   'use strict'
 
   var GOVUK = global.GOVUK || {}
+  var EMAIL_PATTERN = /[^\s=/?&]+(?:@|%40)[^\s=/?&]+/g
+  var POSTCODE_PATTERN = /[A-PR-UWYZ][A-HJ-Z]?[0-9][0-9A-HJKMNPR-Y]?(?:[\s+]|%20)*[0-9][ABD-HJLNPQ-Z]{2}/gi
 
   // For usage and initialisation see:
   // https://github.com/alphagov/govuk_frontend_toolkit/blob/master/docs/analytics.md#create-an-analytics-tracker
 
   var Analytics = function (config) {
+    this.stripPostcodePII = false
+    if (typeof config.stripPostcodePII !== 'undefined') {
+      this.stripPostcodePII = (config.stripPostcodePII === true)
+      // remove the option so we don't pass it to other trackers - it's not
+      // their concern
+      delete config.stripPostcodePII
+    }
     this.trackers = []
     if (typeof config.universalId !== 'undefined') {
       var universalId = config.universalId
@@ -20,6 +29,45 @@
     }
   }
 
+  Analytics.prototype.stripPII = function (value) {
+    if (typeof value === 'string') {
+      return this.stripPIIFromString(value)
+    } else if (Object.prototype.toString.call(value) === '[object Array]') {
+      return this.stripPIIFromArray(value)
+    } else if (typeof value === 'object') {
+      return this.stripPIIFromObject(value)
+    } else {
+      return value
+    }
+  }
+
+  Analytics.prototype.stripPIIFromString = function (string) {
+    var emailStripped = string.replace(EMAIL_PATTERN, '[email]')
+    if (this.stripPostcodePII === true) {
+      return emailStripped.replace(POSTCODE_PATTERN, '[postcode]')
+    } else {
+      return emailStripped
+    }
+  }
+
+  Analytics.prototype.stripPIIFromObject = function (object) {
+    for (var property in object) {
+      var value = object[property]
+
+      object[property] = this.stripPII(value)
+    }
+    return object
+  }
+
+  Analytics.prototype.stripPIIFromArray = function (array) {
+    for (var i = 0, l = array.length; i < l; i++) {
+      var elem = array[i]
+
+      array[i] = this.stripPII(elem)
+    }
+    return array
+  }
+
   Analytics.prototype.sendToTrackers = function (method, args) {
     for (var i = 0, l = this.trackers.length; i < l; i++) {
       var tracker = this.trackers[i]
@@ -36,8 +84,19 @@
     GOVUK.GOVUKTracker.load()
   }
 
+  Analytics.prototype.defaultPathForTrackPageview = function () {
+    // Ignore anchor, but keep query string as per default behaviour of
+    // GA (see: https://developers.google.com/analytics/devguides/collection/analyticsjs/pages#overview)
+    // we ignore the possibility of there being campaign variables in the
+    // anchor because we wouldn't know how to detect and parse them if they
+    // were present
+    return this.stripPIIFromString(window.location.href.split('#')[0])
+  }
+
   Analytics.prototype.trackPageview = function (path, title, options) {
-    this.sendToTrackers('trackPageview', arguments)
+    arguments[0] = arguments[0] || this.defaultPathForTrackPageview()
+    if (arguments.length === 0) { arguments.length = 1 }
+    this.sendToTrackers('trackPageview', this.stripPII(arguments))
   }
 
   /*
@@ -47,11 +106,11 @@
     options.nonInteraction – Prevent event from impacting bounce rate
   */
   Analytics.prototype.trackEvent = function (category, action, options) {
-    this.sendToTrackers('trackEvent', arguments)
+    this.sendToTrackers('trackEvent', this.stripPII(arguments))
   }
 
   Analytics.prototype.trackShare = function (network, options) {
-    this.sendToTrackers('trackSocial', [network, 'share', global.location.pathname, options])
+    this.sendToTrackers('trackSocial', this.stripPII([network, 'share', global.location.pathname, options]))
   }
 
   /*
@@ -59,7 +118,7 @@
     Universal Analytics profile
    */
   Analytics.prototype.setDimension = function (index, value) {
-    this.sendToTrackers('setDimension', arguments)
+    this.sendToTrackers('setDimension', this.stripPII(arguments))
   }
 
   /*

data/app/assets/spec/unit/analytics/analytics.spec.js

@@ -32,6 +32,71 @@ describe('GOVUK.Analytics', function () {
       expect(universalSetupArguments[1]).toEqual(['set', 'anonymizeIp', true])
       expect(universalSetupArguments[2]).toEqual(['set', 'displayFeaturesTask', null])
     })
+
+    it('is configured not to strip postcode data from GA calls', function () {
+      expect(analytics.stripPostcodePII).toEqual(false)
+    })
+
+    it('can be told to strip postcode data from GA calls', function () {
+      analytics = new GOVUK.Analytics({
+        universalId: 'universal-id',
+        cookieDomain: '.www.gov.uk',
+        siteSpeedSampleRate: 100,
+        stripPostcodePII: true
+      })
+
+      expect(analytics.stripPostcodePII).toEqual(true)
+    })
+  })
+
+  describe('tracking pageviews', function () {
+    beforeEach(function () {
+      spyOn(analytics, 'defaultPathForTrackPageview').and.returnValue('https://govuk-frontend-toolkit.example.com/a/page?with=a&query=string')
+    })
+
+    it('injects a default path if no args are supplied', function () {
+      analytics.trackPageview()
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].page).toEqual('https://govuk-frontend-toolkit.example.com/a/page?with=a&query=string')
+    })
+
+    it('injects a default path if args are supplied, but the path arg is blank', function () {
+      analytics.trackPageview(null)
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].page).toEqual('https://govuk-frontend-toolkit.example.com/a/page?with=a&query=string')
+
+      analytics.trackPageview(undefined)
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].page).toEqual('https://govuk-frontend-toolkit.example.com/a/page?with=a&query=string')
+    })
+
+    it('uses the supplied path', function () {
+      analytics.trackPageview('/foo')
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].page).toEqual('/foo')
+    })
+
+    it('does not inject a default title if no args are supplied', function () {
+      analytics.trackPageview()
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].title).toEqual(undefined)
+    })
+
+    it('does not inject a default title if args are supplied, but the title arg is blank', function () {
+      analytics.trackPageview('/foo', null)
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].title).toEqual(undefined)
+
+      analytics.trackPageview('/foo', undefined)
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].title).toEqual(undefined)
+    })
+
+    it('uses the supplied title', function () {
+      analytics.trackPageview('/foo', 'A page')
+      console.log(window.ga.calls.mostRecent().args)
+      expect(window.ga.calls.mostRecent().args[2].title).toEqual('A page')
+    })
   })
 
   describe('when tracking pageviews, events and custom dimensions', function () {
@@ -45,6 +110,46 @@ describe('GOVUK.Analytics', function () {
       analytics.setDimension(1, 'value', 'name')
       expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', 'value'])
     })
+
+    it('strips email addresses embedded in arguments', function () {
+      analytics.trackPageview('/path/to/an/embedded.email@example.com/address/?with=an&email=in.it@example.com', 'an.email@example.com', { label: 'another.email@example.com', value: ['data', 'data', 'someone has added their personal.email@example.com address'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', 'pageview', { page: '/path/to/an/[email]/address/?with=an&email=[email]', title: '[email]', label: '[email]', value: ['data', 'data', 'someone has added their [email] address'] }])
+
+      analytics.trackEvent('an_email@example.com_address-category', 'an.email@example.com-action', { label: 'another.email@example.com', value: ['data', 'data', 'someone has added their personal.email@example.com address'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', { hitType: 'event', eventCategory: '[email]', eventAction: '[email]', eventLabel: '[email]' }]) // trackEvent ignores options other than label or integer values for value
+
+      analytics.setDimension(1, 'an_email@example.com_address-value', { label: 'another.email@example.com', value: ['data', 'data', 'someone has added their personal.email@example.com address'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', '[email]']) // set dimension ignores extra options
+    })
+
+    it('leaves postcodes embedded in arguments by default', function () {
+      analytics.trackPageview('/path/to/an/embedded/SW1+1AA/postcode/?with=an&postcode=SP4%207DE', 'TD15 2SE', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', 'pageview', { page: '/path/to/an/embedded/SW1+1AA/postcode/?with=an&postcode=SP4%207DE', title: 'TD15 2SE', label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] }])
+
+      analytics.trackEvent('SW1+1AA-category', 'SP4%207DE-action', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', { hitType: 'event', eventCategory: 'SW1+1AA-category', eventAction: 'SP4%207DE-action', eventLabel: 'RG209NJ' }]) // trackEvent ignores options other than label or integer values for value
+
+      analytics.setDimension(1, 'SW1+1AA-value', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', 'SW1+1AA-value']) // set dimension ignores extra options
+    })
+
+    it('strips postcodes embedded in arguments if configured to do so', function () {
+      analytics = new GOVUK.Analytics({
+        universalId: 'universal-id',
+        cookieDomain: '.www.gov.uk',
+        siteSpeedSampleRate: 100,
+        stripPostcodePII: true
+      })
+
+      analytics.trackPageview('/path/to/an/embedded/SW1+1AA/postcode/?with=an&postcode=SP4%207DE', 'TD15 2SE', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', 'pageview', { page: '/path/to/an/embedded/[postcode]/postcode/?with=an&postcode=[postcode]', title: '[postcode]', label: '[postcode]', value: ['data', 'data', 'someone has added their personal[postcode] postcode'] }])
+
+      analytics.trackEvent('SW1+1AA-category', 'SP4%207DE-action', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', { hitType: 'event', eventCategory: '[postcode]-category', eventAction: '[postcode]-action', eventLabel: '[postcode]' }]) // trackEvent ignores options other than label or integer values for value
+
+      analytics.setDimension(1, 'SW1+1AA-value', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', '[postcode]-value']) // set dimension ignores extra options
+    })
   })
 
   describe('when tracking social media shares', function () {
@@ -58,6 +163,67 @@ describe('GOVUK.Analytics', function () {
         socialTarget: jasmine.any(String)
       }])
     })
+
+    it('strips email addresses embedded in arguments', function () {
+      analytics.trackShare('email', {
+        to: 'myfriend@example.com',
+        label: 'another.email@example.com',
+        value: ['data', 'data', 'someone has added their personal.email@example.com address']
+      })
+
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', {
+        hitType: 'social',
+        socialNetwork: 'email',
+        socialAction: 'share',
+        socialTarget: jasmine.any(String),
+        to: '[email]',
+        label: '[email]',
+        value: ['data', 'data', 'someone has added their [email] address']
+      }])
+    })
+
+    it('leaves postcodes embedded in arguments by default', function () {
+      analytics.trackShare('email', {
+        to: 'IV63 6TU',
+        label: 'SP4%207DE',
+        value: ['data', 'data', 'someone has added their personalTD15 2SE postcode']
+      })
+
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', {
+        hitType: 'social',
+        socialNetwork: 'email',
+        socialAction: 'share',
+        socialTarget: jasmine.any(String),
+        to: 'IV63 6TU',
+        label: 'SP4%207DE',
+        value: ['data', 'data', 'someone has added their personalTD15 2SE postcode']
+      }])
+    })
+
+    it('strips postcodes embedded in arguments if configured to do so', function () {
+      analytics = new GOVUK.Analytics({
+        universalId: 'universal-id',
+        cookieDomain: '.www.gov.uk',
+        siteSpeedSampleRate: 100,
+        stripPostcodePII: true
+      })
+
+      analytics.trackShare('email', {
+        to: 'IV63 6TU',
+        label: 'SP4%207DE',
+        value: ['data', 'data', 'someone has added their personalTD15 2SE postcode']
+      })
+
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', {
+        hitType: 'social',
+        socialNetwork: 'email',
+        socialAction: 'share',
+        socialTarget: jasmine.any(String),
+        to: '[postcode]',
+        label: '[postcode]',
+        value: ['data', 'data', 'someone has added their personal[postcode] postcode']
+      }])
+    })
   })
 
   describe('when adding a linked domain', function () {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_frontend_toolkit
 version: !ruby/object:Gem::Version
-  version: 7.2.0
+  version: 7.3.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-13 00:00:00.000000000 Z
+date: 2018-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -305,7 +305,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.2
+rubygems_version: 2.7.5
 signing_key: 
 specification_version: 4
 summary: Tools for building frontend applications