0.2.1 • Published 2 years ago
knowable-dom v0.2.1
Knowable DOM
A fully automated user-metrics tracking library for DOM-Based applications. Tracking clicks across your browser application.
Installation
npm i knowable-dom@latest
Basic Setup
import defineKnowable from "knowable-dom";
defineKnowable({
name: "my-app",
tracking: true,
});
Configuration Options
{
// name of your application
name: string;
// the function that determines the "page" field in the request body
getPage?: () => string;
// callback when an analytics event is triggered by "click" | "change" | "error"
onCapture?: (event) => string;
// Uses Navigator.sendBeacon to post the analytical data
apiPath?: string;
// The time delay for the beacon to be sent to the backend
batchDelay?: number;
// Determines when to track everything OR certain things
tracking: {
clicks?: boolean;
changes?: boolean;
errors?: boolean;
} | boolean;
// Skips the Navigator.sendBeacon call and shows verbose console logs
debug?: boolean;
// Customize your analytics
customized?: {
// Can be used to send a specialized "label" to the analytics api
labelElementType?: (target: HTMLElement) => string;
// mutates the listener state for specific targets
applyClickState?: (target: HTMLElement) => State;
// mutates the listener state to "Automatically" add sections to specialized components
autoSection?: (target: HTMLElement) => Event["sections"];
}
}
Request Object
When an event is captured, it will attempt to send a request to a specified endpoint.
Default Endpoint: "/api/track/${config.name}"
{
"sessionId": "ja3iodhjs4fiha", // Unique session based of of the load of the browser tab
"timestamp": 1234719082475, // Date as a number
"page": "", // if using DOM routers then this can be derived from "getPage" function in the config
"sections": { // derived by the "data-section" attributes
"definedSection": true
},
"eventType": "click", // click | change | error
"elementType": "button", // the element where the event occured
"label": "my-button-to-click", // derived from the element or the "data-label" attribute
"to": "string;", // for links "a" tags and etc
"field": "string", // for input fields
"option": "string", // for multi-option fields
"hasValue": true, // for input fields that have a value
"message": "string", // mostly for error events
}
DOM "data" attributes
You can add "data" attributes to divs and other elements that will be captured when this library is listening to events.
For example:
<div data-section="my-div">
<button onclick="func()" data-label="my btn">My Button</button>
</div>
The above code example will have a request object like
{
...
"eventType": "click",
"elementType": "button",
"sections": {
"myDiv": true,
},
"label": "my-btn"
...
}
Related Documentation
Intended to be used for sending analytics data to a web server, and avoids some of the problems with legacy techniques for sending analytics, such as the use of