@lighthouse-analytics/lighthouse-client

Lighthouse Analytics Client

Extensible, lightweight, cookieless and privacy focused analytics library for javascript apps.

Lighthouse Analytics client has a simple and flexible API interface which input data can be channeled to some other analytics service as well as Lighthouse Analytics Server.

Install

Through npm:

npm i @lighthouse-analytics/lighthouse-client

Usage

Initiate the client:

const Lighthouse = require('@lighthouse-analytics/lighthouse-client')
const lighthouse = new Lighthouse()

The developer should initiate a new instance of Lighthouse for each page load. So it is one for SPA's and on each load for classic server rendered sites.

Context

Lighthouse carry a context of the user and app across interactions. The developer may set/update this context any time:

lighthouse.setContext({appName: 'Sample App'})
// later on:
lighthouse.updateContext({userID: 1234})

Services

Services are analytics servers that parses the data came from Lighthouse client and sends it to the server in the appropriate format. Lighthouse is useless without services.

Here is we add Google Analytics service as an example:

const GoogleAnalytics = require('@lighthouse-analytics/lighthouse-service-google-analytics')
const ga = new GoogleAnalytics({id: 'YOUR_GOOGLE_ANALYTICS_PROPERTY_ID'})
lighthouse.addService(ga)

The developer may add as many services as it wants. After adding services, installation is required:

lighthouse.install().then(function() {
  console.log('all services installed and ready to send events.')
})

What Actually Happens When User Visits Your Site/App

First of all, Lighthouse uses only local storage of the visitor's browser/device. There is no cookie created or used by Lighthouse. It's serverless by design.

Identification across visits happen by checking the identifier inside the local storage.

Client reads the following data of the visitor:

1. document.referrer
2. Tab/window visibility state (Through visibility-state-listener)

It listens for visibility changes (if user switched to another tab or window) to better measure time based events.

There is also a time interval which runs every 30 seconds to indicate user's online time.

Internal Events

Lighthouse has its own event-emitter integrated and emits the following internal events for the developer:

lighthouse.on('visibilityChange', function(visibilityState) {
  // visibilityState is "visible" or "hidden"
})
lighthouse.on('online', function() {
  // trigged every 30 seconds independent from the visibility state.
})
lighthouse.on('error', function(name, debug, params) {
  // name is an error identifier
  // debug is the native js error object
  // params is an optional object that contains properties to better understand error

  // INVALID_EVENT_NAME, Error, {name: eventName}
  // NO_SERVICE_INSTALLED, Error
})

Analytics Events

The only events sent by the Lighthouse internally are visibilityChange and online. The developer may create any type of event with any parameters. However, installed services may not be able to take all the parameters you specified while sending the event.

The developer may construct events as the following for example:

view

When user views something. (screen, product etc.)

lighthouse.event('view', {
  category: 'screen', // required
  title: 'Home', // required
  path: '/',
  id: 'homepage',
  url: ''
})

lighthouse.event('view', {
  category: 'product', // required
  title: 'Sample Product', // required
  id: ''
})

time

When something took time to complete.

lighthouse.event('time', {
  category: 'performance', // required
  name: 'stylesheetsLoad', // required
  value: 0 // required, in miliseconds
})

error

When app raises an error.

lighthouse.event('error', {
  message: '', // required
  code: '',
  debug: new Error('asd'),
  level: '' // warning, fatal etc. anything you want.
})

share

When user shares some content.

lighthouse.event('share', {
  channel: 'fb', // required, fb, twitter, email etc.
  title: 'About Section', // required
  id: '',
  url: '' // if content is a complete page
})

click

When user clicks something.

lighthouse.event('click', {
  channel: 'fb', // required, fb, twitter, email etc.
  title: 'About Section', // required
  id: '',
  url: '' // if content is a complete page
})

search

When user searches something.

lighthouse.event('search', {
  term: '' // required
})

read

When user completes reading some content. It is possible with readometer.

const meter = new Readometer()
meter.on('progress', function(progress) {
  console.log('User read ' + progress + ' percent of the text.')
  if (progress >= 75) {
    lighthouse.event('read', {
      title: 'About Section', // required
      percent: progress
    })
  }
})
meter.start( document.getElementById('sample1'), 'en' )