@lighthouse-analytics/lighthouse-client

    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.

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

    Install

    npm i @lighthouse-analytics/lighthouse-client

    DownloadsWeekly Downloads

    8

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    118 kB

    Total Files

    16

    Last publish

    Collaborators

    • muratgozel