AutoCapture.js
A javascript library to capture every user interactions, it provides an easiest and most comprehensive way to
automatically capture the user interactions on the website, from the moment of installation forward. A single snippet
grabs every click, touch, select, and fill — forever.
This library is build with extensibility in mind, it is easy to extend and customize to fit your needs with the help of
the plugin system.
Features
- Automatically captures every user interactions, such as
- Tap
- Click
- Touch
- Double Tap
- Right Click
- Form
- Input
- Select
- Change
- Submit
- Reset
- Scroll
- Mouse Movement
- Swipe
- Page
- Video
- Play
- Pause
- End
- Seek
- Volume Change
- Build-in Plugins
- Extendable with custom plugins
- Lightweight and easy to use
Use Cases
- User Behavior Analysis - Understand how users interact with your site, and how they use your site to achieve their
goals.
- Track User Journeys - Track the user journeys from the moment they land on your site, to the moment they leave.
- Custom Analytics Tool - Build your own analytics tools and libraries using AutoCapture.js to track user behavior,
and use the data to improve your site. e.g. Heatmap, Session Replay, etc.
Live Demo
autocapture-js.vercel.app
Installation
AutoCapture.js is still in development, right now it is in the alpha stage, and it is not ready for production use. The API is not stable yet, and it is subject to change.
NPM
npm install autocapture.js
CDN
<script src='https://unpkg.com/autocapture.js'></script>
Importing library
You can import the library in your project using the following:
import { AutoCapture } from 'autocapture.js';
And to install internal plugins, you can import the plugins in your project using the following:
import { ScrollPlugin, MouseMovementPlugin, PageViewPlugin } from 'autocapture.js';
AutoCapture.use(new ScrollPlugin());
AutoCapture.use(new MouseMovementPlugin());
AutoCapture.use(new PageViewPlugin());
However, you can use CDN to import the library's UMD build in a browser and start using it right away.
Note that the UMD build includes all the plugins, and you don't need to install them separately.
<script src='https://unpkg.com/autocapture.js'></script>
Usage
Using AutoCapture.js is very simple, now you just need to initialize the library with your preferred options.
const instance = new AutoCapture({
safelist: ['input[type="password"]'],
persistence: 'memory',
capture: ['tap', 'form', 'page'],
onEventCapture: (event) => {
console.log('Event stored', event)
}
})
instance.start()
Simple as that - AutoCapture.js will automatically capture all the user interactions on your site, from the moment
of installation forward.
Notable Control Options
- Safelist - Safelist is a list of CSS selectors that you want to ignore. For example, you can ignore all the
password inputs by adding
input[type="password"]
to the safelist. - Persistence - Persistence is the way you want to store the captured events. You can choose between
memory
, localStorage
, sessionStorage
and none
. memory
is the default value.
memory
- Events are stored in memory and are lost when the page is refreshed.localStorage
- Events are stored in the browser's local storage and are persisted across sessions.sessionStorage
- Events are stored in the browser's session storage and are lost when the browser is closed.none
- Events are not stored anywhere.
- Capture - Capture is the list of plugin name. You can choose between
tap
, scroll
, mouse-movement
, page
, video
, form
, swipe
. tap
. But make sure you have installed the plugins you want to use. - onEventCapture - onEventCapture is a callback function that will be called every time an event is captured. You
can use this callback to send the captured events to your server.
- You can use this callback to send the captured events to your server.
- You can use this callback to persist the captured events in your own way.
- You can use this callback to send the captured events to your own analytics tool.
Complete Options List
See the Options interface for the complete list of options.
Option | Type | Default | Description |
---|
safelist | Array | [] | Safelist is a list of CSS selectors that you want to ignore. For example, you can ignore all the password inputs by adding input[type="password"] to the safelist. |
persistence | String | 'memory' | Persistence is the way you want to store the captured events. You can choose between memory , localStorage , sessionStorage and none . memory is the default value. |
capture | Array | ['tap', 'form', 'page'] | A list of plugins to use. Defaults to ['tap', 'form', 'page'] . |
onEventCapture | Function | (capturedEvent: any) => {} | onEventCapture is a callback function that will be called every time an event is captured. You can use this callback to send the captured events to your server. |
elements | Array | ['a', 'button', 'form', 'input', 'select', 'textarea', 'label'] | A list of elements to capture events from. |
attributes | Array | ['text', 'className', 'value', 'type', 'tagName', 'href', 'src', 'id', 'name', 'placeholder', 'title', 'alt', 'role'] | A list of attributes to capture from the elements. |
sessionId | String | '' | Custom session id, you can provide your own visitor id to track the user or use the auto generated one as a default. |
payload | Object | {} | Custom payload to be sent with each event. |
maxEvents | Number | 100 | Specify the maximum number of events to store in the memory, local storage, or session storage and when the limit is reached, the oldest event will be removed. |
maskTextContent | Boolean | false | Specify if you want to mask the text content of the elements. |
Available Public Methods
Method | Description |
---|
start | Start capturing events. |
stop | Stop capturing events. |
clearCapturedEvents | Clear all the captured events from storage. |
getCapturedEvents | Get all the captured events. |
unregisterPlugin | To unregister the installed plugins from the instance. |
Sample Captured Events
{
"event": "click",
"timestamp": "2022-11-03T19:04:22.538Z",
"target": {
"selector": "button",
"attributes": {
"text": "Click Me",
"className": "btn btn-primary",
"type": "button",
"tagName": "BUTTON",
}
},
"meta": {
"devicePixelRatio": 2,
"isBot": false,
"isMobile": false,
"isTouch": false,
"referrer": "",
"screen": {
"width": 1512,
"height": 982
},
"window": {
"width": 793,
"height": 772
},
"scrollDepth": 0,
"timestamp": 1665935720295,
"timezone": -300,
"url": "https://app.autocapture.dev/",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:105.0) Gecko/20100101 Firefox/105.0"
},
"session": "b5b9b9b0-5b9b-4b9b-9b9b-b9b9b9b9b9b9",
"details": {}
}
Details fields are plugin specific. For example, the form
plugin will add the form details to the details
field.
Tap Plugin details field output
{
"details": {
"type": "dblclick",
"x": 123,
"y": 123
}
}
Form Plugin details field output
{
"details": {
"type": "input",
"name": "email",
"action": "https://app.autocapture.dev/",
"method": "POST"
}
}
Page Plugin details field output
{
"details": {
"type": "page-load"
}
}
Mouse Movement Plugin details field output
{
"details": {
"x": 123,
"y": 123
}
}
Scroll Plugin details field output
{
"details": {
"direction": "down",
"percentage": 50,
"speed": 100,
"size": 100
}
}
You can check the output of the other plugins in the Plugin folder.
Extending AutoCapture.js
You can extend AutoCapture.js by creating a new plugin. A plugin is a class that extends the PluginBuilder class.
import { PluginBuilder } from 'autocapture.js';
class MyPlugin extends PluginBuilder {
key = 'some-new-plugin';
bind() {
return [
{
name: 'content-loaded',
target: document,
event: 'DOMContentLoaded',
callback: this._privateMethod,
options: false,
throttle: 1000,
condition: (event) => true
},
]
}
_privateMethod() {
return {
'user-data': {
id: 1,
name: 'John Doe'
}
}
}
}
Check out the Tap/Click Plugin for a sample plugin.
Credits
Made with :heart: by @seeratawan01.
License
MIT License - see the LICENSE file for details.