# 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](https://npmjs.com/package/analytics), which is bundled with [node](https://nodejs.org/) and should be installed as one of your project's dependencies.

```bash
npm install modern-analytics --save
```

## How to use

### Step 1:

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

```ts
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

```javascript
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) <code>string</code> - your app version
- **analyticsUrl** (required) <code>string</code> - your analytics api url
- **userId** (optional) <code>string</code> - user id
- **[disableCustomPlugin]** (optional) <code>boolean</code> - option to disable custom plugin
- **[onAnalyticsError]** (optional) <code>function</code> - request callback on api error
- **[externalPluginsConfig]** (optional) <code>Object</code> - config object to provide details for google analytics plugin use
- **[extraPlugins]** (optional) <code>Record<string,any>[]</code> - 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) <code>string</code> The unique identifier of the event.
- **et** (required) <code>string</code> The type or category of the event.
- **en** (required) <code>string</code> The name of the event.
- **etm** (required) <code>integer</code> The date and time when the event occurred.
- **uid** (required) <code>string</code> The identifier for the user who triggered the event.
- **sid** (optional) <code>string</code> The identifier for the user's session.
- **pn** (optional) <code>string</code> The name of the page where the event occurred.
- **pu** (optional) <code>string</code> The URL of the page where the event occurred.
- **ep** (optional) <code>object</code> Additional event-specific properties as key-value pairs.
- **an** (required) <code>string</code> The name of the app where the event occurred.
- **av** (required) <code>string</code> The version of the app where the event occurred.
- **ua** (required) <code>string</code> The user agent string, which provides additional device and browser information.
- **rf** (optional) <code>string</code> The source URL or referrer, if the event resulted from a referral.
- **eo** (optional) <code>string</code> 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** <code>String</code> - Event name
- **[properties]** (optional) <code>Object</code> - Additional event-specific properties as key-value pairs.

**Example**

```js
// 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) <code>Object</code> - Additional event-specific properties as key-value pairs.

**Example**

```js
// 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:

```javascript
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>
}
```

> **If you want to enable both plugins, set disableCustomPlugin to false and add externalPluginsConfig in details**