---
title: "Integration and Configuration"
slug: "nodejs-integration-and-configuration"
description: "Install the Mapp Intelligence Node.js Library via npm (Node.js 18+) and configure track ID, consumer, queue, timeouts and filters by setter or config file."
status: "update"
updated: 2026-11-02T16:54:13Z
published: 2026-11-02T16:54:13Z
canonical: "docs.mapp.com/nodejs-integration-and-configuration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration and Configuration

## Integration

### NPM

```bash
npm i @mapp-intelligence/node
```

Requires Node.js 18 or newer. Version 1.0.0 no longer supports Node.js 10 to 16.

## Configuration

Create the configuration without arguments, with the track ID and track domain, or with exactly one argument: the path of a configuration file.

```javascript
// empty configuration, set the values with the setters (see Config Object)
const config1 = new MappIntelligenceConfig();

// track ID and track domain
const config2 = new MappIntelligenceConfig("111111111111111", "analytics01.wt-eu02.net");

// path of a configuration file (see Config File)
const config3 = new MappIntelligenceConfig("path/to/your/json/file/config.json");
```

**Config Object**

```javascript
const mappIntelligenceConfig = new MappIntelligenceConfig()
    .setTrackId("111111111111111")
    .setTrackDomain("analytics01.wt-eu02.net")
    .setDomain([])
    .addDomain("")
    .setUseParamsForDefaultPageName([])
    .addUseParamsForDefaultPageName("")
    .setActivateAdvancedPermission(false)
    .setAdvancedPermissionCategory(0)

    .setContainsInclude([])
    .addContainsInclude("")
    .setContainsExclude([])
    .addContainsExclude("")
    .setMatchesInclude([])
    .addMatchesInclude(/regexp/)
    .setMatchesExclude([])
    .addMatchesExclude(/regexp/)

    .setLogger(null)
    .setLogLevel(MappIntelligenceLogLevel.ERROR)
    .setDebug(false)
    .setDeactivate(false)

    .setConsumerType(MappIntelligenceConsumerType.HTTP_CLIENT)
    .setConsumer(null)
    .setFilePath("/tmp")
    .setFilePrefix("MappIntelligenceRequests")
    .setMaxAttempt(1)
    .setAttemptTimeout(100)
    .setMaxBatchSize(50)
    .setMaxQueueSize(1000)
    .setRequestInterval(0)
    .setConnectionTimeout(30 * 1000)
    .setReadTimeout(5 * 1000)
    .setMaxFileLines(10000)
    .setMaxFileDuration(30 * 60 * 1000)
    .setMaxFileSize(24 * 1024 * 1024)

    .setUserAgent("")
    .setClientHintUserAgent("")
    .setClientHintUserAgentFullVersionList("")
    .setClientHintUserAgentMobile("")
    .setClientHintUserAgentModel("")
    .setClientHintUserAgentPlatform("")
    .setClientHintUserAgentPlatformVersion("")
    .setRemoteAddress("")
    .setReferrerURL("")
    .setRequestURL("")
    .setCookie({})
    .addCookie("", "");
```

**Methods**

> [!NOTE]
> Note
> 
> Setting a value: only `null` and `undefined` leave a value unchanged, anything else is taken over, also an empty string, `false` and `0`. A configuration that is reused for the next request therefore has to reset the request data of the previous one, e.g. `setUserAgent('')`, `setRemoteAddress('')` and `setCookie({})`. Creating a new configuration per request is the safest way. The list setters (`setDomain`, `setContainsInclude`, ...) store a copy of the list.

| Methods | Type | Notes | Default | Mandatory |
| --- | --- | --- | --- | --- |
| setTrackId | string | Enter your Mapp Intelligence track ID provided by Mapp. | empty | yes |
| setTrackDomain | string | Enter your Mapp Intelligence tracking URL. | empty | yes |
| setDomain | Array<string \| RegExp> | Specify the domains you do not want to identify as an external referrer (e.g. your subdomains). A string must match the whole domain, a regular expression matches any part of it (use `^` and `$`). Without domains, the domain of the current request URL is used. | empty | no |
| addDomain | string \| RegExp | Specify the domain you do not want to identify as an external referrer (e.g. your subdomains). | empty | no |
| setUseParamsForDefaultPageName | Array<string> | Includes specific URL parameter(s) in the default page name. | empty | no |
| addUseParamsForDefaultPageName | string | Includes specific URL parameter in the default page name. | empty | no |
| setActivateAdvancedPermission | boolean | Enable if you need to differentiate between additional usage options for the tracked data, e.g., only to your Intelligence instance or to both Intelligence and Engage. | false | no |
| setAdvancedPermissionCategory | number | - 0 (default): only Intelligence - 3: Intelligence and Engage Only sent with `setActivateAdvancedPermission(true)`. | 0 | no |
| setContainsInclude | Array<string> | Specify the strings that must be contained in the request URL to measure the request. | empty | no |
| addContainsInclude | string | Specify the string that must be contained in the request URL to measure the request. | empty | no |
| setContainsExclude | Array<string> | Specify the strings that must be contained in the request URL to not measure the request. | empty | no |
| addContainsExclude | string | Specify the string that must be contained in the request URL to not measure the request. | empty | no |
| setMatchesInclude | Array<RegExp \| string> | Specify the regular expressions that must be match the request URL to measure the request. A string is used as a regular expression. | empty | no |
| addMatchesInclude | RegExp | Specify the regular expression that must be match the request URL to measure the request. | empty | no |
| setMatchesExclude | Array<RegExp \| string> | Specify the regular expressions that must be match the request URL to not measure the request. A string is used as a regular expression. | empty | no |
| addMatchesExclude | RegExp | Specify the regular expression that must be match the request URL to not measure the request. | empty | no |
| setLogger | MappIntelligenceLogger | Activates the debug mode. The debug mode sends messages your own LoggerClass (see [MappIntelligenceLogger](/v1/docs/nodejs-interfaces)). | null | no |
| setLogLevel | number \| string | Specify the debug log level as a `MappIntelligenceLogLevel` constant or as a name (case-insensitive, e.g. `"debug"`); other values are ignored: - *NONE:* no logs - *FATAL:* fatal errors - *ERROR*: errors leading to data loss or break code - *WARN:* errors that can affect data quality - *INFO:* general info on configuration and send status - *DEBUG*: general info on request sendout and queue status | ERROR | no |
| setDeactivate | boolean | Deactivate the tracking functionality. | false | no |
| setDebug | boolean | Activates the debug mode with a logger that writes to the console (`console.log`). | false | no |
| setConsumerType | string | Specify the consumer for the data transfer: `MappIntelligenceConsumerType.HTTP_CLIENT`, `FILE`, `FORK_CURL` or `CUSTOM` (see [Data Transfer: Consumer](/v1/docs/nodejs-data-transfer-consumer)). Any other value creates no consumer: nothing is sent and every flush logs an error. | HTTP_CLIENT | no |
| setConsumer | IMappIntelligenceConsumer | Your own consumer (see [Interfaces](/v1/docs/nodejs-interfaces)). If set, it is used with every consumer type, not only with `CUSTOM`. With `CUSTOM` but without a consumer, every flush logs an error and the requests stay in the queue. The cron job does not use it. | null | no |
| setFilePath | string | Directory of the request logging files (FILE consumer). A relative path is resolved against the current working directory of the process. | `os.tmpdir()` | no |
| setFilePrefix | string | Prefix of the request logging files (FILE consumer). | MappIntelligenceRequests | no |
| setMaxAttempt | number | Specify the number of attempts per flush (1 to 5, other values are ignored). After the last attempt, the requests that could not be sent stay in the queue for the next flush. | 1 | no |
| setAttemptTimeout | number | Specify the interval of request resend in milliseconds (1 to 500, other values are ignored). | 100 | no |
| setMaxBatchSize | number | Specify the maximum request number per batch (an integer from 1 to 10,000; a larger value is reduced to 10,000, other values are ignored). A batch is also closed at about 20 MB. Reaching the batch size does not send the queue, see `setRequestInterval`. For the FILE consumer the library always uses 1. | 50 | no |
| setMaxQueueSize | number | Specify the maximum number of requests saved in the queue. When the queue reaches it, the queue is sent; if that fails, the oldest requests are discarded (at least `maxBatchSize`, logged at level WARN). `0` means unlimited, negative values and non-integers are ignored. The cron job always uses an unlimited queue. | 1000 | no |
| setConnectionTimeout | number | Specify the connection timeout in milliseconds (HTTP_CLIENT and FORK_CURL). 0 means no timeout, negative values and non-integers are ignored. There is no config file key for it. | 30 * 1000 | no |
| setReadTimeout | number | Specify the read timeout in milliseconds: how long to wait for data of the response; it is an inactivity timeout, not a limit for the whole response (HTTP_CLIENT). FORK_CURL uses connection + read timeout as the maximum time of the request, only if both are above 0. 0 means no timeout, negative values and non-integers are ignored. There is no config file key for it. | 5 * 1000 | no |
| setRequestInterval | number | Specify the interval in seconds at which the requests are sent automatically. If set to 0, no interval is started: the requests are sent via `flush()`, `close()` or when the queue is full. Negative values and non-integers are ignored. The interval does not keep the process alive. There is no config file key for it. | 0 | no |
| setMaxFileLines | number | The maximum number of lines per file (1 to 10,000). A larger value is reduced to 10,000 and logged at level WARN with the next build, a value below 1 is ignored. | 10 * 1000 | no |
| setMaxFileDuration | number | The maximum file duration in milliseconds (1 to 30 * 60 * 1000). A larger value is reduced to the maximum and logged at level WARN with the next build, a value below 1 is ignored. The cron job uses the same value to take over expired temporary files. | 30 * 60 * 1000 | no |
| setMaxFileSize | number | The maximum file size in bytes (1 to 24 * 1024 * 1024). A larger value is reduced to the maximum and logged at level WARN with the next build, a value below 1 is ignored. | 24 * 1024 * 1024 | no |
| setForceSSL | boolean | **Deprecated**, the value is ignored: every request is sent via SSL (`https://`). Will be removed in a future version. | true | no |
| setUserAgent | string | Enter the origin client HTTP user agent string. | empty | no |
| setClientHintUserAgent | string | Enter the origin Client Hint header for "sec-ch-ua" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentFullVersionList | string | Enter the origin Client Hint header for "sec-ch-ua-full-version-list" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentMobile | string | Enter the origin Client Hint header for "sec-ch-ua-mobile" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentModel | string | Enter the origin Client Hint header for "sec-ch-ua-model" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentPlatform | string | Enter the origin Client Hint header for "sec-ch-ua-platform" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setClientHintUserAgentPlatformVersion | string | Enter the origin Client Hint header for "sec-ch-ua-platform-version" (see [How can I make my website ready for Google Chrome's Client Hints?](/v1/docs/how-can-i-make-my-website-ready-for-google-chromes-client-hints) and [Information on Google Chrome User-Agent Client Hints](/v1/docs/information-on-google-chrome-user-agent-client-hints) for more details). | empty | no |
| setRemoteAddress | string | Enter the origin client Remote address (ip). | empty | no |
| setReferrerURL | string | Enter the origin client HTTP referrer URL. | empty | no |
| setRequestURL | string | Enter the origin client HTTP request URL. An invalid URL removes the previous one. | empty | no |
| setCookie | {[key: string]: string} | Enter a map of all origin client cookies. Replaces the cookies set before. | empty | no |
| addCookie | string | Enter a origin client cookie (key, value). | empty | no |

**Config File (json)**

- A relative path is resolved against the current working directory. The file is read again with every `new MappIntelligenceConfig(path)`, a JavaScript file is executed again.
- If the file cannot be read (missing, invalid JSON), the defaults are used and the error is logged at level ERROR with the next `build()`, for example when the configuration is used for a tracking instance.
- List entries are trimmed and empty entries are dropped (an empty `containsInclude` entry would match every URL).
- `consumer.forceSSL` is ignored, every request is sent via SSL.
- `setConnectionTimeout`, `setReadTimeout`, `setRequestInterval`, `setActivateAdvancedPermission` and `setAdvancedPermissionCategory` have no config file key, set them with the setters.
- A relative `filePath` is resolved against the current working directory of the process, not against the configuration file.

```javascript
const mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/json/file/config.json"
);
```

```javascript
{
    "tracking": {
        "trackId": "111111111111111",
        "trackDomain": "analytics01.wt-eu02.net",
        "deactivate": false,
        "debug": false,
        "logLevel": "DEBUG",
        "domain": [],
        "useParamsForDefaultPageName": [],
        "containsInclude": [],
        "containsExclude": [],
        "matchesInclude": [],
        "matchesExclude": []
    },
    "consumer": {
        "consumerType": "FILE",
        "filePath": "",
        "filePrefix": "",
        "maxAttempt": 1,
        "attemptTimeout": 100,
        "maxBatchSize": 50,
        "maxQueueSize": 1000,
        "maxFileLines": 10000,
        "maxFileDuration": 1800000,
        "maxFileSize": 25165824
    }
}
```

**Config File (js)**

- A relative path is resolved against the current working directory. The file is read again with every `new MappIntelligenceConfig(path)`, a JavaScript file is executed again.
- If the file cannot be read (missing, invalid JSON), the defaults are used and the error is logged at level ERROR with the next `build()`, for example when the configuration is used for a tracking instance.
- List entries are trimmed and empty entries are dropped (an empty `containsInclude` entry would match every URL).
- `consumer.forceSSL` is ignored, every request is sent via SSL.
- `setConnectionTimeout`, `setReadTimeout`, `setRequestInterval`, `setActivateAdvancedPermission` and `setAdvancedPermissionCategory` have no config file key, set them with the setters.
- A relative `filePath` is resolved against the current working directory of the process, not against the configuration file.

```javascript
const mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/js/file/config.js"
);
```

```javascript
// plain CommonJS: Node.js executes the file with require()
const {MappIntelligenceConsumerType, MappIntelligenceLogLevel} = require('@mapp-intelligence/node');

module.exports = {
    tracking: {
        trackId: '111111111111111',
        trackDomain: 'analytics01.wt-eu02.net',
        deactivate: false,
        debug: false,
        logLevel: MappIntelligenceLogLevel.DEBUG,
        domain: [],
        useParamsForDefaultPageName: [],
        containsInclude: [],
        containsExclude: [],
        matchesInclude: [],
        matchesExclude: []
    },
    consumer: {
        consumerType: MappIntelligenceConsumerType.FILE,
        filePath: '',
        filePrefix: '',
        maxAttempt: 1,
        attemptTimeout: 100,
        maxBatchSize: 50,
        maxQueueSize: 1000,
        maxFileLines: 10000,
        maxFileDuration: 1800000,
        maxFileSize: 25165824
    }
};
```