@optimics/article-tracker

Track article content consumption based on DOM events

The ArticleTracker connects to the article container DOM element and tracks its contents using specific ArticleElement classes and then provides unified interface ready for reporting.

• Installation
• Usage
  • ArticleParagraph
  • Custom Element Type
• Metrics object
  • achieved
  • consumed
  • consumableElements
  • consumedElements
  • detected
  • estimates.fastest
  • estimates.slowest
  • overtime
  • timeTotal
• Events
  • consumptionAchievement
  • consumptionStateChanged
  • consumptionStarted
  • consumptionStopped
  • elementsDisplayed
  • elementsConsumed
  • overtime
• Testing
  • Environment variables
  • Known issues

Installation

npm install @optimics/article-tracker

Usage

The basic usage could look like this, if you need to only track article paragraphs.

import { ArticleTracker, ArticleParagraph } from '@optimics/article-tracker'

const articleElement = document.querySelector('#article')
const articleTracker = new ArticleTracker(articleElement, {
  contentTypes: [
    ArticleParagraph
  ]
})

articleElement.on('elementsDisplayed', () => {
  // Connect to your tracking scripts
  console.log(articleTracker.getMetrics())
})
articleElement.on('elementsConsumed', () => {
  // Connect to your tracking scripts
  console.log(articleTracker.getMetrics())
})
articleElement.track()

ArticleParagraph

The ArticleParagraph is a basic Element Type, that only tracks <p> tags content. It estimates slowest and fastest reader time based on the text content size.

The default selector is just 'p'.

import { ArticleParagraph } from '@optimics/article-tracker'

Custom Element Type

import { ArticleTracker, ArticleParagraph, ArticleElement } from '@optimics/article-tracker'

class ArticleVideo extends ArticleElement {
  static selector = '.my-video-player'
  type = 'videos'

  getMetadata() {
    /* In this example, we assume, that video length is stored inside the DOM
     * element like this. It is up to you, to write your bindings
     * <div class="my-video-player" data-player-length="90" /> */
    return this.el.dataset.player
  }

  estimateFastestTime() {
    /* In this example, we assume, that the element can be considered consumed
     * after 75 % of the video length has been played */
    return this.getMetadata().length * 0.75
  }

  estimateSlowestTime() {
    return this.getMetadata().length
  }
}

const articleElement = document.querySelector('#article')
const articleTracker = new ArticleTracker(articleElement, {
  contentTypes: [
    ArticleParagraph,
    ArticleVideo,
  ]
})

Metrics object

The ArticleTracker metrics are split by the Content Types, but also includes aggregated values. When you call articleTracker.getMetrics, you might get something like this:

{
  "achieved": 0.05,
  "consumed": false,
  "overtime": 0,
  "timeTotal": 25,
  "content": {
    "paragraph": {
      "achived": 0.05,
      "consumed": false,
      "consumableElements": 4,
      "consumedElements": 0,
      "detected": 5,
      "displayed": 1,
      "timeTotal": 25,
      "estimates": {
        "fastest": 36.4,
        "slowest": 64.5
      }
    }
  },
  "estimates": {
    "fastest": 36.4,
    "slowest": 64.5
  }
}

The values in the root of the metrics object is aggregated from the individual elements.

achieved

Percentage of how much of the context have been consumed. Rounded to two decimals.

Available on: ArticleMetrics, ContentTypeMetrics

consumed

Each Content Type has specific measurement logic, that determines if it is appropriate to mark it consumed. Let's take ArticleParagraph for example.

The ArticleParagraph estimates the fastest and the slowest consumption time based on the amount of words in the paragraph. We measure time the paragraph spends on screen and when it reached the fastest consumption time, we mark it consumed.

The entire Article is consumed, when all of its elements have been consumed.

Available on: ArticleMetrics, ContentTypeMetrics

consumableElements

How many elements of this type can be consumed? Empty elements of a type are not counted into the consumption metrics. For example empty paragraph would be ignored.

Available on: ContentTypeMetrics

consumedElements

How many elements of this type have been consumed?

Available on: ContentTypeMetrics

detected

How many elements of this type have been detected?

Available on: ContentTypeMetrics

estimates.fastest

Calculated estimate of the fastest time required to consume the entire content in seconds.

estimates.slowest

Calculated estimate of the slowest time required to consume the entire content in seconds.

overtime

Extra time user spent consuming this content. This is a natural number multiplier of the slowest consumer time from TimeEstimates. User, that reached twice the time of slowest consumer will have value 1. Three times the slowest consumer will be 2, and so on. Useful for filtering out unuseful analytics metrics.

Available on: ArticleMetrics

timeTotal

How much time did user spend on the element or article in seconds.

Available on: ArticleMetrics, ContentTypeMetrics

Events

Article Tracker automagically triggers events as result of user interaction. The EventHandler is a function, that returns void and always receives props objects with at least articleTracker instance. All of the events are debounced, so they do not trigger too often.

To subscribe to ArticleTracker event, use the following subscription pattern:

function handler() {
  doSomething()
}
articleTracker.consumptionAchievement.subscribe(handler, options)

Supported events are described below. The options are optional and may be ommited.

• once - when true, the event handler will be triggered only once and then unbound
• conditions - filter the callbacks

consumptionAchievement

Reports progress of consumption achievement. Currently triggered together with elementsConsumed event but the API might change in the future to provide details with higher resolution.

articleTracker.on('consumptionAchievement', ({ articleTracker, achieved }) => {
  console.log(achieved)
})

consumptionStateChanged

Fired when the Article Tracker changes state between "no elements being consumed" and "some elements being consumed". The callback gets passed boolean property consuming. When consuming is true, it means, that some elements in the article are being consumed by the user.

• Debounced event
• Squashed event on consuming

articleTracker.on('consumptionStarted', ({ consuming }) => {
  console.log(consuming)
})

consumptionStarted

Fired when the article tracker changes state from "no elements being consumed" to "some elements being consumed".

• Debounced event by consumptionStateChanged

articleTracker.on('consumptionStarted', ({ articleTracker }) => {
  console.log(articleTracker.getMetrics())
})

consumptionStopped

Fired when the article tracker changes state from "some elements being consumed" to "no elements being consumed".

• Debounced event by consumptionStateChanged

articleTracker.on('consumptionStopped', ({ articleTracker }) => {
  console.log(articleTracker.getMetrics())
})

elementsDisplayed

This is triggered whenever an element, that has not been displayed on page yet, has been diplayed in the page viewport. The event receives targets prop, containing reference to all article elements, that have been displayed since last call.

articleTracker.on('elementsDisplayed', ({ articleTracker, targets }) => {
  console.log(articleTracker.getMetrics())
  console.log(targets)
})

• Debounced event
• Squashed event

elementsConsumed

This is triggered whenever an element, that has not been consumed yet, has met conditions to be marked as consumed. This event receives targets prop, containing reference to all article elements, that have been consumed since last call.

articleTracker.on('elementsConsumed', ({ articleTracker, targets }) => {
  console.log(articleTracker.getMetrics())
  console.log(targets)
})

• Debounced event
• Squashed event

overtime

articleTracker.on('overtime', ({ articleTracker }) => {
  console.log(articleTracker.getMetrics())
})

Event Filtering

Testing

The test suite is a mixture of two environments. JSDOM is used for interface testing and Puppeteer is used for the integration testing to leverage a real Chrome environment. Please note, that Puppeteer tests are not always stable, take long time to run and may sometimes fail due to timeouts and other various instabilities. Rerunning tests on sporadic failures is recommended.

The test suite is included in the repository main test suite.

Environment variables

You can use these variables to develop and debug Puppeteer tests.

TEST_GRAPHIC

Setting TEST_GRAPHIC=true will disable test headless mode and will open actual Chrome window, so you can see the literal behaviour with your own eyes. This is useful when you want to understand what is happening inside the browser.

The browser window will partially take control of your operating system window focus, so you might not be able to fully use your computer during the test. Make sure you select specific test you want to run.

TEST_DEBUG

Setting TEST_DEBUG=true will keep the browser window open for 60 minutes after the test has ended. It implies TEST_GRAPHIC. It is useful, when you want to inspect the Browser Developer Tools

Known issues

The test suite starts subprocesses, that occasionally fail to exit on unexpected test exit. Namingly, this is webpack-dev-server and Chrome browser. This will consume resources of your operating system, eventually rendering it unusable. If you experience issues, like heavy swapping and low memory, terminate them manually.

Unsafe workaround

This will terminate all processes named chrome and node. Do not use it unless you are sure what you are doing.

killall chrome
killall node