Mapp Intelligence - Server-side NodeJS tracking library

Site | Docs | Support | Changelog

Server-side tracking is crucial for companies needing to measure mission-critical information on their website, such as order information or other website goals.

The NodeJS library of Mapp Intelligence helps customers to setup server-side tracking when using Mapp Intelligence as their analysis tool.

The basis for the data collection on your server is implementing the respective library. The Mapp Intelligence tracking library provides scripts to track user behavior and technical information, such as user agents, among others. In addition to the standard data collection, the tracking library offers many options to customize tracking based on specific use cases. Typical use cases are product, order and shipment tracking or the tracking of application processes.

Usage

Requires Node.js 18 or newer. See the documentation in this repository for classes, configuration, data objects, consumers and the cron job, and the changelog for the upgrade notes.

Create one tracking instance per request and close it at the end:

const http = require('http');
const {MappIntelligenceConfig, MappIntelligenceTracking, MappIntelligenceDataMap, MappIntelligencePage} = require('@mapp-intelligence/node');

http.createServer(async (request, response) => {
    const mappIntelligence = new MappIntelligenceTracking(new MappIntelligenceConfig('111111111111111', 'analytics01.wt-eu02.net')
        .setRequestURL('https://' + request.headers['host'] + request.url)
        .setUserAgent(request.headers['user-agent'])
        .setRemoteAddress(request.socket.remoteAddress));
    try {
        await mappIntelligence.track(new MappIntelligenceDataMap().page(new MappIntelligencePage('en.home')));
    } finally {
        await mappIntelligence.close();
    }

    response.end('...');
}).listen(8080);

Development

Requirements

| Software | Version | |------------------|------------:| | docker | 19.0+ | | docker-compose | 1.24+ | | make | |

Without docker: Node.js ^20.19, ^22.13 or >=24 (required by ESLint 10 for development only; the library itself supports Node.js 18+), npm install.

Build

Build, lint and release the package with Node.js 24 inside a docker container. make build only builds the package; make release runs lint, test, build and the smoke test of the build.

$ make build      # dist/ and types/
$ make release    # lint, test, build, smoke test of the build, .release/
$ make lint

Test

The tests run without network access to the Mapp track server: the HTTP and cURL tests use a local HTTPS server with a certificate of a test CA (test/resources/certs, test only).

$ make test             # Node.js 24, or "make test v=20"
$ make test-node18      # one Node.js version: test-node18, test-node20, test-node22, test-node24
$ make test-all         # Node.js 18, 20, 22 and 24
$ make test-latest      # the newest Node.js release
$ make stress-test      # FILE consumer: several processes and a concurrent cron job (local Node.js)

Without docker: npm test, npm run lint, npm run build && npm run test:dist.

Documentation

The documentation in docs/nodejs-library is a Markdown copy of docs.mapp.com.

$ make docs-sync        # downloads the pages listed in docs/docs.txt into docs/nodejs-library

make docs-sync overwrites docs/nodejs-library with the published state: changes made here that are not published yet are lost. Commit or copy them first.

Demo

Start a demo shop example on https://sgu.pixel-test.com (ports 80 and 443, add the host name to your /etc/hosts). The shop uses the library of this repository - run npm run build first.

# start a demo shop example
$ make shop

# ssh access to the demo shop
$ make shop-ssh

# ssh access to the log files of the demo shop
$ make shop-log

# example for cronjob calls
$ make shop-cron-fail
$ make shop-cron-success