Skip to content

cursorinsight/ci-trap-web

Repository files navigation

ci-trap-web test

Lightweight mouse movement tracker library for browsers.

Quickstart

In order to collect mouse, pointer, touch and various other browser events from a website do the following in your ES6 or CommonJS compatible project:

1. Install:

$ npm install ci-trap-web

2. Import trap client using ES6 module syntax:

import trap from 'ci-trap-web';

... or using CommonJS syntax:

const { trap } = require('ci-trap-web');

3. Set up data collection server and start collecting events:

trap.url('https://your.server.com');
trap.mount(document.body);

4. Check for Trap submissions in your network communications, e.g. using your browser's development tools.

Examples

There are working examples in the examples/ directory:

  • ES6 (in examples/es6/) provides a fully configured ES6 compatible example to start integrating Trap into a modern Javascript framework, e.g. React.

  • Vanilla (in examples/vanilla/) contains a precompiled Javascript bundle and the necessary steps to integrate Trap into a bare-bone HTML document -- without the need to set up a complex build framework.

  • Sandbox (in examples/sandbox/) is our experimental sandbox to test and validate new features, execute various research tasks, e.g., saving collected chunks to files into a configurable directory.

Develop

You may want to develop new features or reproduce bugs in a working environment, for this we recommend using our "Sandbox" example in the examples/sandbox/ directory.

Examples are set up. They can be installed and started with these simple commands:

  1. Install the root project's dependencies (in the project's root):

    $ make install-deps
    
  2. Go into the example you want to start -- e.g. "Sandbox" in this case -- and install its dependencies:

    $ cd examples/sandbox/
    $ make install-deps
    
  3. Start the web server to start the example application:

    $ make server
    

The UI of the example is available at http://localhost:3000/.

Configuration

You can configure ci-trap-web by specifying environment variables during build time. These environment variables act as configuration parameters.

You can find the configuration parameters in src/constants.js. Each configuration parameter has a process.env.<name> reference in constants.js.

See the How to generate gt.min.js section for an example that overrides the APP_DEFAULT_TRAP_API_KEY_VALUE configuration parameter.

How to generate gt.min.js

  1. Install the root project's dependencies (in the project's root):

    $ make install-deps
    
  2. Generate a UUID that you will use as the API key (optional):

    $ uuidgen
    aa34677e-a3ee-445c-8483-a30924ebc5d9
    
  3. Build a release (replace the API key):

    $ APP_DEFAULT_TRAP_API_KEY_VALUE=aa34677e-a3ee-445c-8483-a30924ebc5d9 \
          make release
    
  4. You can find your customized gt.min.js as dist/gt.min.js.

How to generate gt.min.js with Docker

You can build assets in a dockerized environment, without the need to install Node.js and its dependencies.

  1. Generate a UUID that you will use as the API key (optional):

    $ uuidgen
    aa34677e-a3ee-445c-8483-a30924ebc5d9
    
  2. Build JavaScript asset files with the Docker environment provided:

    $ docker build --ssh default --build-arg GIT_USER=${GIT_USER} . \
        -t ci-trap-web
    

    Replace ${GIT_USER} with your Gerrit/Git user.

  3. Resulting assets are put into the container's /opt/app/ directory which can be easily accessed after starting the container and using curl or directly copy the files out of it:

    • Start the container:

      $ docker run --rm -p 8080:80 --name ci-trap-web ci-trap-web
      
    • In a separate shell, use curl to fetch the asset:

      $ curl -O http://your-docker-server:8080/gt.min.js
      
    • Or directly copy the file out of it:

      $ docker cp ci-trap-web:/opt/app/gt.min.js ./gt.min.js
      

License

ci-trap-web is released under the MIT license.