Added ability to modify links allowing cross-domain tracking (closes snowplow#109)

Author: fblundun

Gruntfile.js

@@ -163,6 +163,7 @@ module.exports = function(grunt) {
           runType: 'client',
           config: 'tests/intern.js',
           suites: [
+            'tests/nonfunctional/helpers.js',
             'tests/nonfunctional/in_queue.js',
             'tests/nonfunctional/proxies.js'
             ]

examples/web/async-large.html

@@ -29,6 +29,7 @@
           encodeBase64: false, // Default is true
           appId: 'CFe23a', // Site ID can be anything you want. Set it if you're tracking more than one site in this account
           platform: 'mob',
+          crossDomainLinker: function (link) {return link.id === 'legal'}, // Add duid and timestamp to the link with id "legal"
           contexts: {
             performanceTiming: true
           }
@@ -243,7 +244,8 @@ <h2>This shows how two users can simultaneously use Snowplow on the same page wi
     </p>
     <p>
       Middle click the links to trigger link click tracking:<br>
-      <a href=http://en.wikipedia.org/wiki/Main_Page id=legal target="_blank" class="link out">Link</a>
+      <!-- crossDomain functionality correctly alters a link with a multiple question marks and a fragment -->
+      <a href=http://en.wikipedia.org/wiki/Main_Page?a=b?c#fragment id=legal target="_blank" class="link out">Link</a>
       <br>
       <a href=http://en.wikipedia.org/wiki/Main_Page id=illegal class="class barred">Link ignored by one user</a>
     </p>

src/js/lib/helpers.js

@@ -207,4 +207,40 @@
 		}
 	}
 
+	/**
+	 * Add a name-value pair to the querystring of a URL
+	 *
+	 * @param string url URL to decorate
+	 * @param string name Name of the querystring pair
+	 * @param string value Value of the querystring pair
+	 */
+	object.decorateQuerystring = function (url, name, value) {
+		var initialQsParams = name + '=' + value;
+		var hashSplit = url.split('#');
+		var qsSplit = hashSplit[0].split('?');
+		var beforeQuerystring = qsSplit.shift();
+		// Necessary because a querystring may contain multiple question marks
+		var querystring = qsSplit.join('?');
+		if (!querystring) {
+			querystring = initialQsParams;
+		} else {
+			// Whether this is the first time the link has been decorated
+			var initialDecoration = true;
+			var qsFields = querystring.split('&');
+			for (var i=0; i<qsFields.length; i++) {
+				if (qsFields[i].substr(0, name.length + 1) === name + '=') {
+					initialDecoration = false;
+					qsFields[i] = initialQsParams;
+					querystring = qsFields.join('&');
+					break;
+				}
+			}
+			if (initialDecoration) {
+				querystring = initialQsParams + '&' + querystring;
+			}
+		}
+		hashSplit[0] = beforeQuerystring + '?' + querystring;
+		return hashSplit.join('#');
+	}
+
 }());

src/js/tracker.js

@@ -77,6 +77,7 @@
 	 * 14. contexts, {}
 	 * 15. post, false
 	 * 16. bufferSize, 1
+	 * 17. crossDomainLinker, false
 	 */
 	object.Tracker = function Tracker(functionName, namespace, version, mutSnowplowState, argmap) {
 
@@ -269,6 +270,41 @@
 			}
 		}
 
+		/**
+		 * Decorate the querystring of a single link
+		 *
+		 * @param event e The event targeting the link
+		 */
+		function linkDecorationHandler(e) {
+			var duid = loadDomainUserIdCookie()[1];
+			var tstamp = new Date().getTime();
+			var initialQsParams = '_sp=' + duid + '.' + tstamp;
+			var elt = e.target;
+			if (elt.href) {
+				elt.href = helpers.decorateQuerystring(elt.href, '_sp', duid + '.' + tstamp);
+			}
+		}
+
+		/**
+		 * Enable querystring decoration for links pasing a filter
+		 * Whenever such a link is clicked on or navigated to via the keyboard,
+		 * add "_sp={{duid}}.{{timestamp}}" to its querystring
+		 *
+		 * @param function crossDomainLinker Function used to determine which links to decorate
+		 */
+		function decorateLinks(crossDomainLinker) {
+			for (var i=0; i<document.links.length; i++) {
+				var elt = document.links[i];
+				if (!elt.spDecorationEnabled && crossDomainLinker(elt)) {
+					helpers.addEventListener(elt, 'click', linkDecorationHandler);
+					helpers.addEventListener(elt, 'mousedown', linkDecorationHandler);
+
+					// Don't add event listeners more than once
+					elt.spDecorationEnabled = true;
+				}
+			}
+		}
+
 		/*
 		 * Initializes an empty ecommerce
 		 * transaction and line items
@@ -841,6 +877,9 @@
 		 */
 		updateDomainHash();
 
+		if (argmap.crossDomainLinker) {
+			decorateLinks(argmap.crossDomainLinker);
+		}
 
 		/************************************************************
 		 * Public data and methods
@@ -1014,6 +1053,15 @@
 				configDoNotTrack = enable && (dnt === 'yes' || dnt === '1');
 			},
 
+			/**
+			 * Enable querystring decoration for links pasing a filter
+			 *
+			 * @param function crossDomainLinker Function used to determine which links to decorate
+			 */
+			crossDomainLinker: function (crossDomainLinkerCriterion) {
+				decorateLinks(crossDomainLinkerCriterion);
+			},
+
 			/**
 			 * Add click listener to a specific link element.
 			 * When clicked, Piwik will log the click automatically.

tests/nonfunctional/helpers.js

@@ -0,0 +1,101 @@
+/*
+ * JavaScript tracker for Snowplow: tests/nonfunctional/helpers.js
+ *
+ * Significant portions copyright 2010 Anthon Pang. Remainder copyright
+ * 2012-2014 Snowplow Analytics Ltd. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of Anthon Pang nor Snowplow Analytics Ltd nor the
+ *   names of their contributors may be used to endorse or promote products
+ *   derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+define([
+	"intern!object",
+	"intern/chai!assert",
+	"intern/dojo/node!../../src/js/lib/helpers"
+], function (registerSuite, assert, helpers) {
+
+	var decorateQuerystring = helpers.decorateQuerystring;
+
+	registerSuite({
+		name: "decorateQuerystring test",
+		"Decorate a URL with no querystring or fragment": function () {
+			var url = 'http://www.example.com';
+			var expected = 'http://www.example.com?_sp=a.b';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Decorate a URL with a fragment but no querystring": function () {
+			var url = 'http://www.example.com#fragment';
+			var expected = 'http://www.example.com?_sp=a.b#fragment';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Decorate a URL with an empty querystring": function () {
+			var url = 'http://www.example.com?';
+			var expected = 'http://www.example.com?_sp=a.b';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Decorate a URL with a nonempty querystring": function () {
+			var url = 'http://www.example.com?name=value';
+			var expected = 'http://www.example.com?_sp=a.b&name=value';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Override an existing field": function () {
+			var url = 'http://www.example.com?_sp=outdated';
+			var expected = 'http://www.example.com?_sp=a.b';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Decorate a URL whose querystring contains multiple question marks": function () {
+			var url = 'http://www.example.com?test=working?&name=value';
+			var expected = 'http://www.example.com?_sp=a.b&test=working?&name=value';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Override a field in a querystring containing a question mark": function () {
+			var url = 'http://www.example.com?test=working?&_sp=outdated';
+			var expected = 'http://www.example.com?test=working?&_sp=a.b';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+
+		"Decorate a querystring with multiple ?s and #s": function () {
+			var url = 'http://www.example.com?test=working?&_sp=outdated?&?name=value#fragment?#?#';
+			var expected = 'http://www.example.com?test=working?&_sp=a.b&?name=value#fragment?#?#';
+			var actual = decorateQuerystring(url, '_sp', 'a.b');
+			assert.equal(actual, expected);
+		},
+	});
+});