Add activity tracking callback mechanism (close #765)

Author: jamessnowplow

examples/web/activity-tracking.html

@@ -30,6 +30,7 @@
     "grunt-contrib-concat": "^1.0.1",
     "grunt-contrib-uglify": "^4.0.1",
     "jest": "^24.9.0",
+    "jest-date-mock": "^1.0.7",
     "jest-dev-server": "^4.3.0",
     "js-base64": "^2.4.9",
     "lodash": "^4.17.15",
@@ -66,5 +67,8 @@
     "test:unit": "jest tests/unit/*.spec.js",
     "test:e2e:sauce": "docker pull snowplow/snowplow-micro && wdio tests/wdio.sauce.conf.js",
     "test:e2e:local": "docker pull snowplow/snowplow-micro && wdio tests/wdio.local.conf.js"
+  },
+  "jest": {
+    "setupFiles": ["jest-date-mock"]
   }
 }

npm-shrinkwrap.json

@@ -150,7 +150,8 @@
 			configReferrerUrl = locationArray[2],
 
 			// Holder of the logPagePing interval
-			pagePingInterval,
+			pagePingInterval = null,
+			pagePingCallbackInterval = null,
 
 			customReferrer,
 
@@ -348,7 +349,11 @@
 			preservePageViewId = false,
 
 			// Whether first trackPageView was fired and pageViewId should not be changed anymore until reload
-			pageViewSent = false;
+			pageViewSent = false,
+
+			// Activity tracking config for callback and pacge ping variants
+			activityTrackingConfig = {},
+			activityTrackingCallbackConfig = {};
 
 		// Object to house gdpr Basis context values
 		let gdprBasisData = {};
@@ -1550,7 +1555,7 @@
 			// Send ping (to log that user has stayed on page)
 			var now = new Date();
 
-			if (activityTrackingEnabled && !activityTrackingInstalled) {
+			if ((activityTrackingConfig.activityTrackingEnabled || activityTrackingCallbackConfig.activityTrackingEnabled) && !activityTrackingInstalled) {
 				activityTrackingInstalled = true;
 
 				// Add mousewheel event handler, detect passive event listeners for performance
@@ -1607,22 +1612,39 @@
 
 				// Periodic check for activity.
 				lastActivityTime = now.getTime();
-				clearInterval(pagePingInterval);
-				pagePingInterval = setInterval(function heartBeat() {
-					var now = new Date();
-
-					// There was activity during the heart beat period;
-					// on average, this is going to overstate the visitDuration by configHeartBeatTimer/2
-					if ((lastActivityTime + configHeartBeatTimer) > now.getTime()) {
-						// Send ping if minimum visit time has elapsed
-						if (configMinimumVisitTime < now.getTime()) {
-							logPagePing(finalizeContexts(context, contextCallback)); // Grab the min/max globals
-						}
-					}
-				}, configHeartBeatTimer);
+			}
+
+			if (activityTrackingConfig.activityTrackingEnabled && pagePingInterval === null && activityTrackingInstalled) {
+				pagePingInterval = activityInterval({
+					...activityTrackingConfig,
+					callback: args => logPagePing({ context: finalizeContexts(context, contextCallback), ...args }) // Grab the min/max globals
+				});
+			}
+
+			if (activityTrackingCallbackConfig.activityTrackingEnabled && pagePingCallbackInterval === null && activityTrackingInstalled) {
+				pagePingCallbackInterval = activityInterval(activityTrackingCallbackConfig);
 			}
 		}
 
+		function activityInterval({ activityTrackingEnabled, configHeartBeatTimer, configMinimumVisitTime, callback }) {
+			if (!activityTrackingEnabled) return;
+
+			return setInterval(function heartBeat() {
+				var now = new Date();
+
+				// There was activity during the heart beat period;
+				// on average, this is going to overstate the visitDuration by configHeartBeatTimer/2
+				if ((lastActivityTime + configHeartBeatTimer) > now.getTime()) {
+					// Send ping if minimum visit time has elapsed
+					if (configMinimumVisitTime < now.getTime()) {
+						refreshUrl();
+						callback({ pageViewId: getPageViewId(), minXOffset, minYOffset, maxXOffset, maxYOffset });
+						resetMaxScrolls();
+					}
+				}
+			}, configHeartBeatTimer);
+		}
+
 		/**
 		 * Log that a user is still viewing a given page
 		 * by sending a page ping.
@@ -1631,8 +1653,7 @@
 		 *
 		 * @param context object Custom context relating to the event
 		 */
-		function logPagePing(context) {
-			refreshUrl();
+		function logPagePing({ context, minXOffset, minYOffset, maxXOffset, maxYOffset }) {
 			var newDocumentTitle = documentAlias.title;
 			if (newDocumentTitle !== lastDocumentTitle) {
 				lastDocumentTitle = newDocumentTitle;
@@ -1647,7 +1668,6 @@
 				cleanOffset(minYOffset),
 				cleanOffset(maxYOffset),
 				addCommonContexts(context));
-			resetMaxScrolls();
 		}
 
 		/**
@@ -2052,9 +2072,33 @@
 		apiMethods.enableActivityTracking = function (minimumVisitLength, heartBeatDelay) {
 			if (minimumVisitLength === parseInt(minimumVisitLength, 10) &&
 				heartBeatDelay === parseInt(heartBeatDelay, 10)) {
-				activityTrackingEnabled = true;
-				configMinimumVisitTime = new Date().getTime() + minimumVisitLength * 1000;
-				configHeartBeatTimer = heartBeatDelay * 1000;
+				activityTrackingConfig = {
+					activityTrackingEnabled: true,
+					configMinimumVisitTime: new Date().getTime() + minimumVisitLength * 1000,
+					configHeartBeatTimer: heartBeatDelay * 1000
+				}
+			} else {
+				helpers.warn("Activity tracking not enabled, please provide integer values " +
+					"for minimumVisitLength and heartBeatDelay.")
+			}
+		};
+
+		/**
+		 * Enables page activity tracking (replaces collector ping with callback).
+		 *
+		 * @param int minimumVisitLength Seconds to wait before sending first page ping
+		 * @param int heartBeatDelay Seconds to wait between pings
+		 * @param function callback function called with ping data
+		 */
+		apiMethods.enableActivityTrackingCallback = function (minimumVisitLength, heartBeatDelay, callback) {
+			if (minimumVisitLength === parseInt(minimumVisitLength, 10) &&
+				heartBeatDelay === parseInt(heartBeatDelay, 10)) {
+				activityTrackingCallbackConfig = {
+					activityTrackingEnabled: true,
+					configMinimumVisitTime: new Date().getTime() + minimumVisitLength * 1000,
+					configHeartBeatTimer: heartBeatDelay * 1000,
+					callback
+				}
 			} else {
 				helpers.warn("Activity tracking not enabled, please provide integer values " +
 					"for minimumVisitLength and heartBeatDelay.")

package.json

@@ -0,0 +1,144 @@
+/*
+ * JavaScript tracker for Snowplow: tests/functional/activityCallback.spec.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.
+ */
+import F from 'lodash/fp'
+
+describe('Activity tracking with callbacks', () => {
+  if (
+    F.isMatch(
+      { version: '12604.5.6.1.1', browserName: 'safari' },
+      browser.capabilities
+    )
+  ) {
+    fit('skipping in safari 11 (saucelabs)', () => {})
+  }
+  if (
+    F.isMatch(
+      { version: '12603.3.8', browserName: 'safari' },
+      browser.capabilities
+    )
+  ) {
+    // the safari driver sauce uses for safari 10 doesnt support
+    // setting cookies, so this whole suite fails
+    // https://github.com/webdriverio/webdriverio/issues/2004
+    fit('skipping in safari 10 (saucelabs)', () => {})
+  }
+
+  it('reports events on scroll', () => {
+    browser.url('/activity-callback.html?test1')
+    browser.waitUntil(
+      () => $('#init').getText() === 'true',
+      5000,
+      'expected init after 5s'
+    )
+
+    $('#bottomRight').scrollIntoView()
+
+    browser.waitUntil(
+      () => +$('#numEvents').getText() >= 1,
+      10000,
+      'expected >= 1 event after 10s'
+    )
+    const [maxX, maxY] = browser.execute(() => {
+      return [findMaxX(), findMaxY()]
+    })
+
+    expect(maxX).toBeGreaterThan(100)
+    expect(maxY).toBeGreaterThan(100)
+  })
+
+  it('carries pageviewid change through and resets scroll', () => {
+    browser.url('/activity-callback.html?test2')
+    browser.waitUntil(
+      () => $('#init').getText() === 'true',
+      5000,
+      'expected init after 5s'
+    )
+
+    const firstPageViewId = browser.execute(() => {
+      var pid
+      getCurrentPageViewId(function(id) {
+        pid = id
+      })
+      return pid
+    })
+
+    $('#bottomRight').scrollIntoView()
+    $('#middle').scrollIntoView()
+    browser.waitUntil(
+      () => +$('#numEvents').getText() >= 1,
+      10000,
+      'expected >= 1 event after 10s'
+    )
+
+    browser.execute(() => {
+      trackPageView()
+    })
+    $('#bottomRight').scrollIntoView()
+
+    browser.waitUntil(
+      () => +$('#numEvents').getText() > 1,
+      10000,
+      'expected > 1 event after 10s'
+    )
+
+    const secondPageViewId = browser.execute(() => {
+      var pid
+      getCurrentPageViewId(function(id) {
+        pid = id
+      })
+      return pid
+    })
+
+    // sanity check
+    expect(firstPageViewId).not.toEqual(secondPageViewId)
+
+    const first = browser.execute(id => {
+      return findLastEventForPageViewId(id)
+    }, firstPageViewId)
+    const second = browser.execute(id => {
+      return findLastEventForPageViewId(id)
+    }, secondPageViewId)
+
+    const getMinXY = F.at(['minXOffset', 'minYOffset'])
+
+    // the first page view starts at 0,0
+    expect(getMinXY(first)).toEqual([0, 0])
+
+    // but the second starts at #bottomRight and only moves as far as #middle
+    // so there is no way it can get to 0,0
+    const [secondX, secondY] = getMinXY(second)
+    expect(secondX).toBeGreaterThan(0)
+    expect(secondY).toBeGreaterThan(0)
+  })
+})