neuro-id v4.0.0-alpha12

TrackJS

This project contains tools for building and deploying Neuro-ID's TrackJS JavaScript library.

Requirements

npm > v6.0.0

Setup

npm install

Deploy

npm run build
npm run deploy

Run Unit Tests

We use Webpack along with the Mocha test framework to compile and run our unit tests.

npm run start:mocha

This command will serve the Mocha test report on http://localhost:8080/. You can then view the report in your local browser or in BrowserStack using the BrowserStack Chrome plugin.

Run Unit Tests on BrowserStack

We user the Karma Test Runner to run our automated tests on BrowserStack.

karma start karma.conf.js

Browser Support

• Google Chrome
• Firefox
• Safari
• Opera
• IE9

Documentation

Current URL Identification

This library has an option to track when the url changes. This is an important functionality for timing metrics, as the metrics require the timestamp of when the page is first viewed. This functionality can be enabled by configuring the stateChangeListener option. Currently there are two options:

• manual
• automatic

The manual option requires the client to call nid.stateChange('${location}') command. We will rely on the client configuring this event correctly.

The automatic option will use a setInterval() command to poll the current window location and determine if this has been changed. Given the variety of JS frameworks and browsers that we support, this is the most simplistic approach to detecting a URL change.

Libraries using a similar pattern:

• hotjar - 200ms listening pattern

Other libraries use a more sophisticated approach by listening to browser state commands. We have considered both the hashChange and popState listeners, however, these events may be obfuscated by some JS frameworks. That would require additional configuration to ensure we recieve these events per client integration. This area may be worth exploring in the future, but the current implementation does meet the current need.

Libraries using this pattern:

• Google url-change-tracker.js
• Mouseflow uses the React history module (React must be in use on site)

Queue Flushing

By default the queue is flushed every 6000ms (6 seconds). This option is configurable using the eventQueFlushInterval option. The queue is also flushed on key events to prevent data loss. These key events are:

• State Change
• Set User Id
• Tag
• Set Variable
• Window Blur
• Target Blur

Because of the frequency of these events we have implemented a throttle function to prevent the queue from flushing too raplidy. This throttle timeout is configurable using the eventQueueThrottleWait option. The lowest throttle time recommended is 400ms. This has been tested on various browsers using high latency options. Given the standard of 4-6 parallel network requests on a browser this is the lowest time that safely prevents the library from sending too many requests. There is also a requestTimeout option that defaults to 4000ms. Given the requestTimeout we can throttle to the exact amount of parallel requests we expect if desired. For example, if every request took 4000ms, and the eventQueueThrottleWait option was set to 1000ms, the library would only use 4 parallel threads. On a fast network connection, the average flush command only takes 60-120ms.

Event Target Metadata Collection

Event List

We collect target metadata for various input events. These events are:

• keydown
• keyup
• mousemove
• mousedown
• mouseup
• focusin
• focusout
• copy
• cut
• paste
• input
• invalid
• submit
• reset

Touch specific events:

• touchstart
• touchmove
• touchend

Change events:

• textchange
• radiochange
• checkboxchange
• selectchange

Metadata collected

The target metadata collected is:

• neuro-id target selector (determined through default selectors)
• tag name
• element type
• url
• all attributes that match the list of whitelisted regular expressions

Expresssion matching

The attributeWhitelist attribute can be used to white list attributes to collect. Since we dont necessarily want to collect all attributes this allows us to filter attributes to ones we are interested in. Our default patterns are: ['^id$', '^name$', '^data-*$', '^neuro-*$'] We can "blacklist" attributes through regular expressions. For example if we want to collect all attributes that start with data- but exclude data-pii attribute we would have the following expression: ['^id$', '^name$', '^data-(?!pii).*$'] as shown in test cases.