Modern-analytics NPM

modern-analytics

An Modern Analytics!

What is this repository for?

A lightweight analytics abstraction library for tracking page views & custom events. This library has support of custom analytics plugin and google analytics plugin.

Install

This module is distributed via npm, which is bundled with node and should be installed as one of your project's dependencies.

npm install modern-analytics --save

How to use

Step 1:

Wrap App component with AnalyticsProvider which is imported from modern-analytics package

import React from 'react'
import { BrowserRouter as Router } from 'react-router-dom'
import { AnalyticsProvider } from 'modern-analytics'

function App() {
  return (
    <Router basename='/'>
      <AnalyticsProvider>
        <ModernPages /> //Application Pages
      </AnalyticsProvider>
    </Router>
  )
}

export default App

Step 2:

We have to setDetails that are required for custom analytics using setAnalyiticDetails function provided by useAnalyticsContext hook inside your ModernPages component

import { useAnalyticsContext } from 'modern-analytics'

const ModernPages = () => {
  const { analytics, setAnalyiticDetails } = useAnalyticsContext()
  useEffect(() => {
    setAnalyiticDetails({
      appName: 'your appName',
      appVersion: 'your appVersion',
      analyticsUrl: 'your analytics Url where data will store',
      userId: 'your userId',
    })
  }, [])

  return <div>ModernPages</div>
}

setAnalyticDetails

This callback function is used to set required details for analytics.

Arguments

appVersion (required) string - your app version
analyticsUrl (required) string - your analytics api url
userId (optional) string - user id
disableCustomPlugin (optional) boolean - option to disable custom plugin
onAnalyticsError (optional) function - request callback on api error
externalPluginsConfig (optional) Object - config object to provide details for google analytics plugin use
extraPlugins (optional) Record<string,any>[] - option to provide custom plugins from outside

analyticsUrl

Here analyticsUrl is api endpoint which is used to save data using post request. This request will contain some payload which will expect following attributes:

eid (required) string The unique identifier of the event.
et (required) string The type or category of the event.
en (required) string The name of the event.
etm (required) integer The date and time when the event occurred.
uid (required) string The identifier for the user who triggered the event.
sid (optional) string The identifier for the user's session.
pn (optional) string The name of the page where the event occurred.
pu (optional) string The URL of the page where the event occurred.
ep (optional) object Additional event-specific properties as key-value pairs.
an (required) string The name of the app where the event occurred.
av (required) string The version of the app where the event occurred.
ua (required) string The user agent string, which provides additional device and browser information.
rf (optional) string The source URL or referrer, if the event resulted from a referral.
eo (optional) string The outcome or result of the event, if applicable.

Step 3:

To collect the data we have to call functions provided by anlytics instance which are following

analytics.track

Track an analytics event. This will trigger track calls in any installed plugins

Arguments

eventName String - Event name
properties (optional) Object - Additional event-specific properties as key-value pairs.

Example

// Basic event tracking
analytics.track('buttonClicked')

// Event tracking with properties
analytics.track('buttonClicked', {
  price: 11,
  sku: '1234',
})

analytics.page

Trigger page view. This will trigger page calls in any installed plugins

Arguments

properties (optional) Object - Additional event-specific properties as key-value pairs.

Example

// Basic page tracking
analytics.page()

// Page tracking with page data
analytics.page({
  pageData: 'xyz page',
})

Other plugin support

For now this library supports two plugin custom plugin and google analytics plugin. To use google analytics, just pass config required for google analytics in externalPluginsConfig key.

For using google analytics v4 please provide measurement ids array in googleAnalyticsV4MeasurementIds and for using google analytics v3 please provide tracking id string in googleAnalyticsV3TrackingId.

Here is a quick example of a plugin:

import { useAnalyticsContext } from 'modern-analytics'

const ModernPages = () => {
  const { analytics, setAnalyiticDetails } = useAnalyticsContext()
  useEffect(() => {
    setAnalyiticDetails({
      appName: 'appName',
      appVersion: 'appVersion',
      analyticsUrl: 'Url',
      userId: 'userId',
      externalPluginsConfig: {
        googleAnalyticsV4MeasurementIds: ['id1', 'id2'],
        googleAnalyticsV3TrackingId: 'id3',
      },
      disableCustomPlugin: true,
    })
  }, [])

  return <div>ModernPages</div>
}