home.md

+## Introduction
+
+_**Web Analytics Web Lib**_ is a Javascript library used to define and detect events on a web page and send them to an endpoint where they can be analyzed.
+
+## Initialization
+
+The library has to be included in every page you need to use it on:
+```html
+<script src="PATH/web-analytics.js"></script>
+```
+followed by the initialization script or file:
+```html
+<script>
+(function() {
+   
+    const options = {
+        siteId: 'SITE_ID',
+        principalId: 'PRINCIPAL_ID'
+    };
+
+    new WebAnalytics(options);
+
+})();
+</script>
+```
+
+## Initialization options
+
+- **siteId** : _string **required**_ : site ID
+- **principalId** : _string **required**_  : principal ID
+- **eventsConfigurationFile** : _string_ `undefined` : URL to the events configuration file
+- **setCustomerCode** : _function_ `() => {}` : custom function to store/save the customer code
+- **getCustomerCode** : _function_ `() => undefined` : custom function to return the customer code
+- **getDomain** : _function_ `() => undefined` : returns a valid cookie domain string (example: '' | '.domain.com' | 'domain.com' | 'sub.domain.com')
+- **blockAllEvents** : _function_ `(workunit) => false` : when this function returns true all the events will not be sent
+- **blockLowLevelEvents** : _function_ `(workunit) => false` : when this function returns true the "low level" events will not be sent
+- **trackTimeOnPage** : _boolean_ `false` : when set to true, the library will track the active time spent on every page
+- **debug** : _boolean_ `false` : sent events will show up in the console logs when this parameter is true
+
+example:
+```html
+<script>
+(function() {
+    const getDomain = () => {
+        // return a valid cookie domain string (example: '' | '.domain.com' | 'domain.com' | 'sub.domain.com')
+        return '';
+    };
+
+    const setCustomerCode = () => {
+        // set cookie or variable with customer code
+    };
+    
+    const getCustomerCode = () => {
+        // get variable or cookie containing the customer code and return it
+        return 'CUSTOMER_CODE';
+    };
+
+    const blockAllEvents = (workunit) => {
+        return false;
+    };
+    const blockLowLevelEvents = (workunit) => {
+        return true;
+    };
+
+    const options = {
+        siteId: 'SITE_ID',
+        principalId: 'PRINCIPAL_ID',
+        eventsConfigurationFile: './web-analytics/eventsConfiguration.js',
+        setCustomerCode,
+        getCustomerCode,
+        getDomain,
+        blockAllEvents,
+        blockLowLevelEvents,
+        trackTimeOnPage: false,
+        debug: true
+    };
+
+    new WebAnalytics(options);
+
+})();
+</script>
+```
+
+### Blocking Events Conditionally
+
+`blockAllEvents` and `blockLowLevelEvents` receive the input parameter `workunit`.
+
+Its informations can be used to choose if the events contained inside it will be sent or not.
+
+Workunit example:
+```js
+workunit = {
+    browserName: "Firefox"
+    browserVersion: "88.0"
+    items: Array(40) [ {…}, {…}, {…}, … ] // array of events about to be sent
+    language: "en-US"
+    osName: "Windows"
+    osVersion: "10"
+    principalId: "PRINCIPAL_ID"
+    screenHeight: 1308
+    screenWidth: 1778
+    siteId: "SITE_ID"
+    userId: "CqVggqFpqcKc1qxciNW5F"
+    version: "1.1.1" // library version
+}
+```