Changelog

1.0.0 (2026-10-27)

Upgrade notes

The API is compatible, but check the following changes before you upgrade. The first two may require changes to your code.

• Node.js 18 or newer is required.

• Sending: Adding a request no longer sends a batch when maxBatchSize is reached. The queue is sent with flush(), close(), when it reaches maxQueueSize, or every requestInterval seconds. A long-lived instance (for example a singleton) that relied on maxBatchSize, such as setMaxBatchSize(1), has to call flush() or set setRequestInterval(). (see Integration and Configuration)

• Close tracking instances: Create one instance per request and await close() it at the end. close() sends the remaining requests. (see Classes)

• No more process listeners: The library no longer listens to SIGINT, SIGTERM, SIGUSR1, SIGUSR2 and uncaughtException. Close the instances in your own shutdown handler, otherwise queued requests can be lost when the process ends.

• HTTPS only: All requests are sent via HTTPS. setForceSSL() and consumer.forceSSL are ignored.

• Permanent errors discard requests: 5xx, 408 and 429 are retried. Other 4xx responses discard the batch, for example because of a wrong track ID. flush() and close() resolve to false if a batch was discarded. (see Data Transfer: Consumer)

• maxQueueSize takes effect: A full queue is sent. If sending fails, the oldest requests are discarded. 0 means unlimited.

• Configuration values: Only null and undefined keep the current value. An empty string, false and 0 are applied. setCookie() replaces the cookies instead of adding them. A relative path to the configuration file is resolved against the current working directory.

• Timeouts: The HTTP consumer waits at most 30 seconds for the connection and aborts a request if no response data arrives for 5 seconds (setConnectionTimeout(), setReadTimeout()).

• Campaigns without an ID: The campaign is now read from the media codes of the request URL, so campaigns may be tracked where nothing was sent before. (see Campaign)

• Hybrid: Only pixel requests (parameter p, max. 64 KB) are logged. IP address and user agent sent by the client are removed.

• Cron job: Requests that can never be sent are kept in *.log.discarded, and the run continues with the next file. Runs without files to send and runs that overlap another run end with exit status 0. An unsupported option ends with exit status 1. Only files named <prefix>-<timestamp>… are processed. (see Cron Job)

• Queue: addRequestAsString() and addRequestAsObject() are private. Use add().

Features

• Lifecycle: close() for MappIntelligenceTracking and MappIntelligenceHybrid, flush() for MappIntelligenceHybrid, and the callback setOnFlushComplete().

• Request interval: setRequestInterval() sends the queue periodically.

• Custom consumers: New optional methods send(), with the result SENT, RETRY or DISCARDED, and close(). (see Interfaces)

• Campaigns: setMediaCode() and setOncePerSession() now work server-side, with new getters.

• HTTP consumer: Connections are reused, and timeouts are configurable.

• Engage registration: New fields for ISO code, ISO language and time zone. (see Mapp Engage)

• Engage attributes: All scalar value types are accepted (boolean, bigint, string, number).

• Hybrid: isValidPixelRequest() and MAX_REQUEST_LENGTH.

Bugfixes

• Security: In hybrid tracking, a client could set X-WT-IP and X-WT-UA and so pretend to be another user. The FORK_CURL consumer no longer passes the payload to a shell command. The everID is generated with a cryptographically secure random number.

• Lost or duplicate requests: Fixed for several processes (for example cluster or PM2) and the cron job writing to the same files, for requests still queued at process end, for failing custom consumers, for overlapping cron job runs, and for partially sent, unreadable or undeletable log files.

• Blocked queue: A batch above the size limits or answered with a permanent error no longer blocks all following requests.

• Stability: A memory leak and endless loops are fixed (for example with maxBatchSize 0). The application ends normally after SIGTERM, SIGINT or an uncaught exception.

• Performance: The file consumer writes about 10 times faster.

• Reused objects: A reused parameter map or configuration no longer carries data of the previous request into the next one.

• Request data: Request URLs with encoded characters or // in the path, referrers without protocol, invalid characters and null, NaN or Infinity values are handled correctly. Boolean Engage attributes are no longer dropped.

• Configuration: The log level "NONE" works, and regular expressions with the flag g match reliably.

• Cron job: The predefined cron job script reports errors instead of swallowing them.

0.3.0 (2025-10-17)

Feature

• Personally Identifiable Information data sent to Engage for the registration process (see Registration)

• It is now possible to send Mapp Engage Custom Attributes (see Engage)

• We want to enable customers to distinguish between forwarding data to Intelligence only or to Intelligence and Engage (see Configuration)

0.2.0 (2023-09-04)

Feature

• New product status added

0.1.1 (2023-08-07)

Feature

• Support temporary session ID (see Data)

0.1.0 (2023-05-08)

Feature

• Include advanced logging (see Integration and Configuration)

• Support UserAgent Client Hints (see Integration and Configuration)

0.0.5 (2023-01-26)

Feature

• Include method to suppress certain requests (see Integration and Configuration)

0.0.4 (2022-10-17)

Optimization

• Add tracking parameter (pf, cs801 and cs802) for tracking feature usage

0.0.3 (2021-07-15)

Feature

• MappIntelligenceHybrid returns the image directly as Buffer

0.0.2 (2021-07-14)

Feature

• Add mapp-intelligence-node as bin file

0.0.1 (2021-07-14)

• Beta release