@aller/blink/README.md

A library for tracking user behaviour.

<p align="center">
  <img src="logo.svg" />
</p>

# blink

Library for user behaviour tracking.

## Goals

The main goal is to make it easy to track user behavior on our sites.

- easy to configure
- fast
- small bundle size
- only collects and stores what is necessary
- ability to track multiple pages at the same time

## Trackers

We have six "types" of trackers:

- Pageload tracking
- Active time tracking
- Impression tracking
- Ad tracking
- Click tracking
- Video tracking

In addition, we expose one custom tracker type to fill miscellaneous needs.

## Usage

```javascript
import createBlink from '@aller/blink';

const blink = createBlink({
  send: event => console.log(event),
  persistState: (key: string, state: any) => void,
  utils: {
    getPersistedState: (key: string) => any,
    getArticleBodyTop: () => number,
    getArticleBodyHeight: () => number,
    getClientWidth: () => document.documentElement.clientWidth,
    getClientHeight: () => document.documentElement.clientHeight,
    getScrollHeight: () => document.documentElement.scrollHeight,
  },
  useDevTools: true, // redux devtools enabled
});

// Initialize a new "page",
// flushes state, and creates a new uuid for the pageView
blink.pageInit({
  abCookie: 51,
  commercialSegments: 'sport,soccer,gardening',
  pageId: 'front-page',
  pageType: 'instant-article',
  referrer: 'www.dinside.no',
  site: 'www.dagbladet.no',
  url: 'http://dinside.no/a/93289234',
  userId: 'f7a8cad1-773a-4041-b81f-bd1bf9843465',
});

// Track a when the page loads
blink.pageLoad({
  pageId: 'front-page',
  cmId: 'c9e0eb73-cdde-45f4-a2a0-2811d24ff5b4',
  plussData: { hasAccess: true, customerNumber: '123' },
  url: 'http://dinside.no/a/93289234',
});

// Track that the user clicked on an element / article
blink.click({
  pageId: 'front-page',
  url: 'http://seher.no/a/12931093',
});

/**
 * AD-RELATED FUNCTIONS
 */

// Track that an ad entered the screen by 30% og 50%, depending on the ad size
blink.adScreenEnter({ id: 'ad-topbanner' });

// Track that an ad left the screen, by having less than 30% or 50% inside view
blink.adScreenExit({id: 'ad-topbanner' });

// Track that an ad entered the screen by the first pixel
blink.adScreenEnter0({ id: 'ad-medium-rectangle' });

// Track that an ad is completely out of the screen
blink.adScreenExit0({id: 'ad-medium-rectangle' });

// Track that an ad started loading
blink.adLoad({ id: 'ad-medium-rectangle', offsetTop: 200, offsetHeight: 450, scrollTop: 100 });

// Track data that is gotten from DFP, with internals only known by DFP gurus
blink.dfpImpressionViewable({
  id: 'ad-medium-rectangle',
  scrollTop: 100
});

blink.dfpSlotRenderEnded({
  id: 'ad-medium-rectangle',
  adUnitPath: '/8578/dagbladet.no/seksjoner/kjendis/artikkel',
  advertiserId: 29318043,
  campaignId: 123018391,
  creativeId: 123908149018,
  lineItemId: 344329408239,
  size: [300, 250]
  sourceAgnosticCreativeId: 123908149018,
  sourceAgnosticLineItemId: 344329408239,
  scrollTop: 100
});
blink.dfpSlotOnload({
  id: 'ad-medium-rectangle1',
 name: 'medium-rectangle1',
 scrollTop: 100,
});

/**
 * ARTICLE-RELATED FUNCTIONS
 */

// Track that an article preview went into screen
blink.articlePreviewScreenEnter({
  url: 'http://seher.no/kjendis/surprising-title/123980243',
  title: 'Surprising title!',
  height: 380,
  width: 400,
  personalizationParametersRequested: 'xavier-pluss',
  personalizationSystemUsed: 'cerebro',
  position: 5,
});
// Track that an article preview went out of screen
blink.articlePreviewScreenExit('http://seher.no/kjendis/surprising-title/123980243');

// Tracking of the users total activity time on a given article
pageActivityStart('http://seher.no/kjendis/surprising-title/123980243', 0.43); // sets the user as active for the next 10 seconds, unless a stop event is sent
pageActivityStop('http://seher.no/kjendis/surprising-title/123980243'); // sets the user as inactive, and sends active time data
```

## API

### PageInit

Should be called on a page initialization. Sets the pageView and computes values that will not change over the course of the page view.

```javascript
pageInit({ url, pageView, previousPageView });
```

### Pageload

```javascript
pageLoad({ url, cmId, plussData });
```

### Clicks

```javascript
click({ url });
```

### Ads

```javascript
adScreenEnter({ id });
adScreenExit({ id });
adScreenEnter0({ id });
adScreenExit0({ id });
adLoad({ id, scrollTop, scrollHeight });

// DFP Events
dfpImpressionViewable({ id });
dfpSlotRenderEnded({
  id,
  adUnitPath,
  advertiserId,
  campaignId,
  creativeId,
  lineItemId,
  size,
  sourceAgnosticCreativeId,
  sourceAgnosticLineItemId,
});
dfpSlotOnload({ id, name });
```

### Impression

```javascript
articlePreviewScreenEnter({
  url: string,
  title: string,
  height: number,
  width: number,
  personalizationParametersRequested: string,
  personalizationSystemUsed: string,
  position: integer,
});
articlePreviewScreenExit({ url });
```

### Active Time

```javascript
pageActivityStart({ url, maxScroll }); // sets the user as active for the next 10 seconds, unless a stop event is sent
pageActivityStop({ url }); // sets the user as inactive, and sends active time data
```

### Video

```javascript
videoPlay({
  videoId: string,
  muted: boolean,
  volume: number,
  position: number,
  reason: 'autostart' | 'interaction',
});

videoStop({
  videoId: string,
  muted: boolean,
  volume: number,
  position: number,
  reason: 'pause' | 'complete' | 'exit',
});

videoAd({
  videoId: string,
  adPosition: 'pre' | 'mid' | 'post',
});
```

### Player

```javascript
playerShown({
  playerId: string,
  muted: boolean,
  volume: number,
  position: number,
  reason: 'viewable' | 'tabactive',
});

playerHidden({
  playerId: string,
  muted: boolean,
  volume: number,
  position: number,
  reason: 'viewable' | 'tabhide' | 'tabclose',
});
```

### Custom

```javascript
custom({
  customDomain: string,
  customType: string,
  customContent: string,
  customValue: integer,
});
```