Add ability to override send event function

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
      */