cimice
v0.7.0
Published
Experimental user session recorder
Downloads
7
Readme
Cimice
Cimice is an experimental user session recorder. The goal is to recreate, at least in part, the core function of already popular cloud services available online (see below).
Features
- Built-in support for
click
,mousemove
,scroll
andresize
events - No dependencies
- Easily extendible
Installation
All you need is cimice.min.js
file inside /dist
folder that you can get from the cloned repo via git clone https://github.com/artf/grapesjs.git
/ npm install cimice
or download it directly from here
Development
Clone the repository and enter inside the folder
$ npm install cimice
$ cd cimice
Install all necessary dependencies
$ npm install
Start dev server
$ npm run dev
Usage
Below you can see some of the real live examples on how to use Cimice for better fit your needs.
Recording
Example 1 (quick but not recommended)
Record the entire site and send data to some endpoint every 5 seconds
let rec = new cimice.Recorder({
target: document.documentElement
});
rec.startRecording();
setInterval(() => {
let json = JSON.stringify(rec.getMovie());
let xhr = new XMLHttpRequest();
xhr.open('POST', 'https://your/endpoint');
xhr.send(json);
}, 5000);
Example 2
The first example is simple but there is a big overhead as you send always all recorded frames
and keep them in memory.
Furthermore, you could potentially send data even without user interaction and that is pretty annoying.
In the example I use XMLHttpRequest
, to send data over the net, only for the simplicity but you can replace it with your favorite alternative (JQuery, socket.io, etc)
let rec = new cimice.Recorder({
target: document.documentElement
});
// At first, when the recording starts I want to be sure to send initial
// data about the movie/target/screen
rec.on('startRecording', () => {
let movieJson = JSON.stringify(rec.getMovie());
let xhr = new XMLHttpRequest();
xhr.open('POST', 'https://save/movie');
xhr.send(movieJson);
});
// Next listener sends last new recorded frames every 50 interactions (with default mousemove
// event it's already pretty much high frequency) and remove them from the collection.
// Anyway this logic is pretty much simple but ok as example, I suggest to build your own.
rec.on('recording', () => {
let movie = rec.getMovie();
let frames = movie.getFrames();
let framesJson = JSON.stringify(frames);
if(!(frames.length % 50)){
let xhr = new XMLHttpRequest();
xhr.open('POST', 'https://save/frames');
xhr.send(framesJson);
movie.setFrames([]);
}
});
rec.startRecording();
Playing
// Here I supposed to have all recorded data inside fetched movie, but following the
// second recording example you could probably have to fetch also frames data. So
// you could have to do something like this:
// let movieJSON = fetchMovie();
// let framesJSON = fetchFrames(); // Should be an array of objects
// movieJSON.frames = framesJSON;
// let movie = new cimice.Movie(movieJSON);
let movieJSON = fetchMovie();
let movie = new cimice.Movie(movieJSON);
let player = new cimice.Player({
target: document.getElementById('some-div')
});
player.setMovie(movie);
player.play();
Extend
Cimice comes out of the box with few recordable events (click, mousemove, scroll and resize), but you can extend this behavior. In the example below you will see how to track right mouse click (of course only the click itself, no context menu will pop up)
Track right mouse click
// RECORDER
// At first, init your recorder to be able to listen right click events (contextmenu)
let rec = new cimice.Recorder({
target: document.documentElement,
events: ['mousemove', 'click', 'scroll', 'resize', 'contextmenu']
});
rec.startRecording();
// ... your logic to store data
// PLAYER
// ... fetch your movie and frames data
let movie = new cimice.Movie(movieJSON);
let player = new cimice.Player({
target: document.getElementById('some-div')
});
player.setMovie(movie);
player.on('contextmenu', function(frame){
let dot = document.createElement("div");
dot.style.backgroundColor = 'blue';
dot.style.width = '10px';
dot.style.height = '10px';
dot.style.borderRadius = '100%';
dot.style.marginLeft = '-5px';
dot.style.marginTop = '-5px';
dot.style.position = 'absolute';
dot.style.left = player.getCursorX() + 'px';
dot.style.top = player.getCursorY() + 'px';
player.getTarget().appendChild(dot);
});
player.play();
API
You can find API Reference here. The documentation is generated via documentationjs so if there is something to fix/add do it inside the code not API file itself
Testing
Simple test run
$ npm test
Run and watch test
$ npm run test:dev
Cool cloud services
If you're looking for something serious I suggest to checkout this list. If you know others feel free to pull request
Known issues & limitations
- In Firefox, when you click 'play' button, for some reason, it will add the necessary iframe but immediately after will reload it, so you'll see nothing. One other click on 'play' should display iframe correctly
- In Safari, 'play' won't work. Seems like there is an issue with writing inside iframe (working on this)
- Dynamic contents (eg. via AJAX) are not supported.
Why cimice?
Cimice /ˈtʃimitʃe/
, in italian, means literally a bug, but in this context supposed to be a wiretap
License
MIT