https://github.com/springload/springload-analytics
https://github.com/springload/springload-analytics
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/springload/springload-analytics
- Owner: springload
- Created: 2020-11-13T03:42:28.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-05-24T02:14:15.000Z (over 4 years ago)
- Last Synced: 2024-11-28T14:20:20.155Z (about 1 year ago)
- Language: TypeScript
- Size: 107 KB
- Stars: 3
- Watchers: 7
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Springload Analytics
> Event tracker inspired by springload-analytics.js.
This library rewrite the previous `springload-analytics.js` to and add integration of `Perfume.js` to track the performance metrics in browser.
## Install
```bash
npm install @springload/springload-analytics
yarn add @springload/springload-analytics
```
## Basic setup
```javascript
import * as SpringloadAnalytics from "springload-analytics";
const { googleAnalyticsPlugin, tecPlugin } = SpringloadAnalytics;
SpringloadAnalytics.init({
trackerPlugins: [
googleAnalyticsPlugin({
trackingId: "UA-12341131-6",
}),
tecPlugin({
trackerUrl: "/event";
applicationVersion: "ert7565456asd";
})
]
});
```
The built-in google analytics tracker now is replaced by manually passsing tracker plugins in to initialization function which allow users to customize their own tracker based on project requirement.
## Performance metrics
**Perfume.js** is a tiny, web performance monitoring library that reports field data back to your favorite analytics tool.
`springload-analytics` sends performance metrics to Google Analytics using **perfume.js**.
**Perfume.js** tracks the following performance mertrics:
- First Paint (fp)
- First Contentful Paint (fcp)
- Largest Contentful Paint (lcp)
- Largest Contentful Paint Final (lcpFinal)
- First Input Delay (fid)
- Cumulative Layout Shift (cls) 0-0.1
- Cumulative Layout Shift Final (clsFinal)
- Total Blocking Time (tbt)
- Total Blocking Time 5S (tbt5S)
- Total Blocking Time 10S (tbt10S)
- Total Blocking Time Final (tbtFinal)
Performance tracking is enabled by passing performancePlugin instance to `trackerPlugins` is initialization funciton argument, You can specific the trackers you would like the tracking data be sent to in `sendTo` otherwise the data will be sent to all trackers.
```javascript
import * as SpringloadAnalytics from 'springload-analytics';
const { performancePlugin } = SpringloadAnalytics;
SpringloadAnalytics.init({
trackerPlugins: [
// ...other tracker plugins
performancePlugin({
sendTo: ['google-analytics'],
}),
],
});
```
## API Reference
### Configuration
After initialization with config, the core API is exposed & ready for use in the application.
| Option | Default | Description |
| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| trackerPlugins | `[]` | The tracker plugins |
| debug | 'false' | Whether open debug mode |
| separator | '|' | The charactor used to separate the content of `data-analytics` attribute into tracking variables `category`, `event`, `label` and `value`. |
| trackableAttribute | 'analytics' | The attribute name following `data-` attached to the trackable elements. |
| trackableEvent | 'click' | The event need to be tracked on trackable elements. |
| payloadKeys | `[]` | The property keys array that related to the values in the same sequence in trackable attribute separated by separator. |
```javascript
SpringloadAnalytics.init({
separator: ":"
trackableAttribute: "sp-analytics",
trackableEvent: "hover",
payloadKeys: ["label", "data"]
});
```
### Page
Trigger page view measurement calls in Google analytics.
**Arguments:**
- [data] (optional) PageData - Page data overrides.
- [options] (optional) Object - Page tracking options
- [callback] (optional) Function - Callback to fire after page view call completes
```javascript
// Basic page tracking
SpringloadAnalytics.page();
// Page tracking with page data overrides
SpringloadAnalytics.page({
url: 'https://google.com',
});
// Fire callback with 1st, 2nd or 3rd argument
SpringloadAnalytics.page(() => {
console.log('do this after page');
});
// Send pageview to only to specific analytic tools
SpringloadAnalytics.page({}, ['google-ana']);
```
## Custom tracking
Custom targeted tracking you can specify event data by populating the data-analytics attribute with pipe (|) separated values.
```javascript
SpringloadAnalytics.setupTrackables({
event: 'Link click',
payloadKeys: ['category', 'label', 'value'],
});
```
```html
```
## Tracking dynamically
You can track within a JavaScript file by calling the track method, just specify the event and pass the event data which will be sent to trackers:
```javascript
// Specify event and payload.
SpringloadAnalytics.track(event, {
label,
value,
category,
});
// Specify the trackers that will receive the payload, by default it'll be sent to all tracker.
SpringloadAnalytics.track(
event,
{
label,
data,
},
['tec']
);
```
## Setup additional trackable elements on the fly
You can set up additional/alternative trackable elements on the fly by calling `setupTrackables`:
```javascript
SpringloadAnalytics.setupTrackables({
trackableAttribute: 'google-analytics',
trackableEvent: 'mouseenter',
separator: ':',
event: 'hover read more',
payloadKeys: ['page', 'section'],
sendTo: ['google-analytics'], // Not specific it will send to all trackers
});
```
The markup for this example would be:
```html
Read more
```