1.0.2 • Public • Published

    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.


    Through npm:

    npm i @lighthouse-analytics/lighthouse-client


    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.


    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 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'})

    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}

    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:


    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: ''


    When something took time to complete.

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


    When app raises an error.

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


    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


    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


    When user searches something.

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


    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' )


    npm i @lighthouse-analytics/lighthouse-client

    DownloadsWeekly Downloads






    Unpacked Size

    118 kB

    Total Files


    Last publish


    • muratgozel