Skip to content

F
foresight
Commit 2129c69f by James Ooi
Options

Add ability to override send event function

parent 370a70de
Showing with 114 additions and 50 deletions
README.md
# Foresight
### Foresight is an analytics library that allows for declarative event tracking in your websites.
### Foresight is an analytics library that allows for declarative event tracking.
* Lightweight (<3kb minified and gzipped)
* Declarative event tracking
......@@ -9,7 +9,7 @@
### Direct download
Download and install the latest distribution file from this
Git repository and load it in your webpage. For production cases, we encourage you to download the minified version ([`foresight.min.js`](#))
Git repository and load it in your webpage. For production cases, we encourage you to download the minified version ([`foresight.min.js`](blob/master/dist/foresight.min.js))
```html
<script src="/path/to/foresight.min.js"></script>
......@@ -94,19 +94,19 @@ The above markup would send the following event data when the `div` enters the v
## Configuration
```ts
```js
{
/** Defer tracking initialisation. */
defer?: boolean
defer: false
/** Configure the intersection observer. */
observerOptions?: IntersectionObserverConfig
observerOptions: { /* Refer to Intersection Observer documentation */ }
/** Treat clicks as an interactive event. Defaults to `true`. */
clicksAreInteractions?: boolean
clicksAreInteractions: true
/** Treat views as an interactive event. Defaults to `false`. */
viewsAreInteractions?: boolean
viewsAreInteractions: false
}
```
......@@ -140,4 +140,16 @@ Parameters:
---
#### `send(data: EventData)`
Manually send an analytics event data.
Parameters:
* `data: EventData` An object containing the event data with the following keys:
* `category: string`
* `action: string`
* `label: string`
* `interaction: boolean`
---
Copyright © 2018 FOREFRONT International Sdn Bhd.
\ No newline at end of file
dist/foresight.js
......@@ -121,8 +121,7 @@ var __assign = (this && this.__assign) || function () {
__webpack_require__(1);
var Utils = __webpack_require__(2);
/**
* Foresight is an analytics library that allows for declarative event tracking
* in your websites.
* Foresight is an analytics library that allows for declarative event tracking.
* @class
*/
var Foresight = /** @class */ (function () {
......@@ -130,6 +129,7 @@ var Foresight = /** @class */ (function () {
* @constructor
*/
function Foresight(config) {
if (config === void 0) { config = {}; }
var _this = this;
/**
* Stores a mapping of elements with is respective functions to de-register
......@@ -158,20 +158,18 @@ var Foresight = /** @class */ (function () {
}
}
/**
* Start event tracking for all DOM elements with event tracking attributes.
* Start tracking all elements with tracking attributes for events.
* @param {Element} root The container to scan for elements. Defaults to `body`.
*/
Foresight.prototype.start = function (root) {
var _this = this;
if (root === void 0) { root = document.body; }
if (gtag === undefined) {
throw "The 'gtag' function is undefined. Has Google Analytics been loaded yet?";
}
Utils
.toArray(root.querySelectorAll('[data-track], [data-track-view]'))
.map(function (element) { return _this.track(element); });
};
/**
* Enables event tracking for a DOM element with event tracking attribute.
* Start tracking an element for events.
*/
Foresight.prototype.track = function (element) {
if (!this._untrackFns.has(element)) {
......@@ -193,7 +191,7 @@ var Foresight = /** @class */ (function () {
this._untrackFns.set(element, untrackFn);
};
/**
* Disable event tracking for a DOM element.
* Stop tracking an element for events.
*/
Foresight.prototype.untrack = function (element) {
var untrackFn = this._untrackFns.get(element);
......@@ -209,6 +207,31 @@ var Foresight = /** @class */ (function () {
this._untrackFns.delete(element);
};
/**
* Manually send an analytics event data.
*/
Foresight.prototype.send = function (data) {
if (this.options.sendEventFn !== null) {
return this.options.sendEventFn(data);
}
if (typeof window['gtag'] === 'function') {
return window['gtag']('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
}
if (typeof window['ga'] === 'function') {
return window['ga']('send', {
hitType: 'event',
eventCategory: data.category,
eventAction: data.action,
eventLabel: data.label,
nonInteraction: !data.interaction,
});
}
throw 'No available analytics backend found. Has Google Analytics been loaded yet?';
};
/**
* Parse an event string and returns a `EventData` object.
* @private
*/
......@@ -267,11 +290,7 @@ var Foresight = /** @class */ (function () {
if (element.getAttribute('data-track:non-interaction') !== null) {
data.interaction = false;
}
gtag('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
this.send(data);
};
/**
* Handles a view event on an element that is being tracked by Foresight.
......@@ -284,11 +303,7 @@ var Foresight = /** @class */ (function () {
if (element.getAttribute('data-track-view:interaction') !== null) {
data.interaction = true;
}
gtag('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
this.send(data);
};
/**
* Default Options
......@@ -296,9 +311,10 @@ var Foresight = /** @class */ (function () {
*/
Foresight.defaultOptions = {
defer: false,
observerOptions: {},
clicksAreInteractions: true,
viewsAreInteractions: false,
observerOptions: {},
sendEventFn: null,
};
return Foresight;
}());
......
src/foresight.ts
......@@ -27,6 +27,9 @@ interface ForesightConfig {
/** Treat views as an interactive event. Defaults to `false`. */
viewsAreInteractions?: boolean
/** Override the default send event function. */
sendEventFn?: (data: EventData) => any
}
/**
......@@ -41,8 +44,7 @@ interface EventData {
/**
* Foresight is an analytics library that allows for declarative event tracking
* in your websites.
* Foresight is an analytics library that allows for declarative event tracking.
* @class
*/
class Foresight {
......@@ -56,6 +58,7 @@ class Foresight {
observerOptions: {},
clicksAreInteractions: true,
viewsAreInteractions: false,
sendEventFn: null,
}
/**
......@@ -104,10 +107,6 @@ class Foresight {
* @param {Element} root The container to scan for elements. Defaults to `body`.
*/
start(root: Element = document.body) {
if (gtag === undefined) {
throw `The 'gtag' function is undefined. Has Google Analytics been loaded yet?`;
}
Utils
.toArray<Element>(root.querySelectorAll('[data-track], [data-track-view]'))
.map(element => this.track(element));
......@@ -162,6 +161,35 @@ class Foresight {
}
/**
* Manually send an analytics event data.
*/
send(data: EventData) {
if (this.options.sendEventFn !== null) {
return this.options.sendEventFn(data);
}
if (typeof window['gtag'] === 'function') {
return window['gtag']('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
}
if (typeof window['ga'] === 'function') {
return window['ga']('send', {
hitType: 'event',
eventCategory: data.category,
eventAction: data.action,
eventLabel: data.label,
nonInteraction: !data.interaction,
})
}
throw 'No available analytics backend found. Has Google Analytics been loaded yet?';
}
/**
* Parse an event string and returns a `EventData` object.
* @private
*/
......@@ -230,11 +258,7 @@ class Foresight {
data.interaction = false;
}
gtag('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
this.send(data);
}
/**
......@@ -250,11 +274,7 @@ class Foresight {
data.interaction = true;
}
gtag('event', data.action, {
'event_label': data.label,
'event_category': data.category,
'non_interaction': !data.interaction,
});
this.send(data);
}
}
......
typings/foresight.d.ts
......@@ -14,14 +14,24 @@ interface ForesightConfig {
defer?: boolean;
/** Configure the intersection observer. */
observerOptions?: IntersectionObserverInit;
/** Treat clicks as an interactive event. Defaults to true. */
/** Treat clicks as an interactive event. Defaults to `true`. */
clicksAreInteractions?: boolean;
/** Treat views as an interactive event. Defaults to false. */
/** Treat views as an interactive event. Defaults to `false`. */
viewsAreInteractions?: boolean;
/** Override the default send event function. */
sendEventFn?: (data: EventData) => any;
}
/**
* Foresight is an analytics library that allows for declarative event tracking
* in your websites.
* Represents a particular event's data.
*/
interface EventData {
category: string;
action: string;
label: string;
interaction: boolean;
}
/**
* Foresight is an analytics library that allows for declarative event tracking.
* @class
*/
declare class Foresight {
......@@ -49,20 +59,25 @@ declare class Foresight {
/**
* @constructor
*/
constructor(config: ForesightConfig);
constructor(config?: ForesightConfig);
/**
* Start event tracking for all DOM elements with event tracking attributes.
* Start tracking all elements with tracking attributes for events.
* @param {Element} root The container to scan for elements. Defaults to `body`.
*/
start(root?: Element): void;
/**
* Enables event tracking for a DOM element with event tracking attribute.
* Start tracking an element for events.
*/
track(element: Element): void;
/**
* Disable event tracking for a DOM element.
* Stop tracking an element for events.
*/
untrack(element: Element): void;
/**
* Manually send an analytics event data.
*/
send(data: EventData): any;
/**
* Parse an event string and returns a `EventData` object.
* @private
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment