---
title: "Integration and Configuration"
slug: "integration-and-configuration"
description: "Add the Mapp Intelligence Java library via Maven or Gradle and configure it in code or with a properties or XML file. All options and defaults."
status: "update"
updated: 2026-11-02T16:48:28Z
published: 2026-11-02T16:48:28Z
canonical: "docs.mapp.com/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

### Maven

```xml
<dependency>
    <groupId>com.mapp.intelligence.tracking</groupId>
    <artifactId>tracking</artifactId>
    <version>1.1.1</version>
</dependency>
```

### Gradle

```bash
implementation group: 'com.mapp.intelligence.tracking', name: 'tracking', version: '1.1.1'
```

## Configuration

**Config Object**

```java
MappIntelligenceConfig mappIntelligenceConfig = new MappIntelligenceConfig()
    .setTrackId("111111111111111")
    .setTrackDomain("analytics01.wt-eu02.net")
    .setDomain(new ArrayList<String>())
    .addDomain("")
    .setUseParamsForDefaultPageName(new ArrayList<String>())
    .addUseParamsForDefaultPageName("")
    .setActivateAdvancedPermission(false)
    .setAdvancedPermissionCategory(0)

    .setContainsInclude(new ArrayList<String>())
    .addContainsInclude("")
    .setContainsExclude(new ArrayList<String>())
    .addContainsExclude("")
    .setMatchesInclude(new ArrayList<String>())
    .addMatchesInclude("")
    .setMatchesExclude(new ArrayList<String>())
    .addMatchesExclude("")

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

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

    .setUserAgent("")
    .setClientHintUserAgent("")
    .setClientHintUserAgentFullVersionList("")
    .setClientHintUserAgentMobile("")
    .setClientHintUserAgentModel("")
    .setClientHintUserAgentPlatform("")
    .setClientHintUserAgentPlatformVersion("")
    .setRemoteAddress("")
    .setReferrerURL("")
    .setRequestURL("")
    .setCookie(new HashMap<String, String>())
    .addCookie("", "");
```

Track ID and track domain can also be passed to the constructor directly: `new MappIntelligenceConfig("111111111111111", "analytics01.wt-eu02.net")`. To read the configuration from a file, see the tabs Config File (properties) and Config File (XML).

**Methods**

| 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 | List<String> | Specify the domains you do not want to identify as an external referrer (e.g. your subdomains). If the list is empty, the host of the request URL is used. | empty | no |
| addDomain | String | Specify the domain you do not want to identify as an external referrer (e.g. your subdomains). | empty | no |
| setUseParamsForDefaultPageName | List<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 | Integer | If activateAdvancedPermission is activated: - 0 (default): only Intelligence - 3: Intelligence and Engage | 0 | no |
| setContainsInclude | List<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 | List<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 | List<String> | Specify the regular expressions that must match the request URL to measure the request (a partial match is enough). An invalid expression is logged as an error and ignored. | empty | no |
| addMatchesInclude | String | Specify the regular expression that must be match the request URL to measure the request. | empty | no |
| setMatchesExclude | List<String> | Specify the regular expressions that must be match the request URL to not measure the request. | empty | no |
| addMatchesExclude | String | 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/interfaces)). Without a logger, nothing is logged. | null | no |
| setLogLevel | String or int | Specify the debug log level, either as name (case-insensitive) or as `MappIntelligenceLogLevel` constant (0 to 5, see [Classes](/v1/docs/classes)). An unknown value is 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 |
| setConsumerType | String | Specify the [consumer](/v1/docs/data-transfer-consumer) to use for data transfer to Intelligence ( *HTTP_CLIENT*, *FILE* or *CUSTOM*). With `CUSTOM` but without `setConsumer` (or with an unknown type), no consumer exists: every flush logs an error and the requests stay in the queue. `MappIntelligenceHybrid` sets every type except `CUSTOM` to `FILE` (see [Classes](/v1/docs/classes)). | HTTP_CLIENT | no |
| setConsumer | MappIntelligenceConsumer | Specify the custom consumer to use for data transfer to Intelligence (see [MappIntelligenceConsumer](/v1/docs/interfaces)). If set, it is used for sending regardless of the consumer type. It is not closed by the library. | null |  |
| setFilePath | String | Enter the directory of your request logging files, with or without a trailing path separator. This is only relevant when using file consumer. | System.getProperty("java.io.tmpdir") + "/" | no |
| setFilePrefix | String | Enter the prefix from your request logging files. This is only relevant when using file consumer. | MappIntelligenceRequests | no |
| setMaxAttempt | Integer | Specify the number of send attempts per flush (1 to 5). After the maxAttempts have been reached, the requests that could not be sent **stay in the queue** and are sent again with the next flush or when the instance is closed. Batches that can never be sent (for example after a permanent client error) are discarded, see [Data Transfer: Consumer](/v1/docs/data-transfer-consumer). | `1` | no |
| setAttemptTimeout | Integer | Specify the interval of request resend in milliseconds (1 to 500). | 100 | no |
| setConnectionTimeout | Integer | Specify the number for connection timeout in milliseconds. | 30 * 1000 | no |
| setReadTimeout | Integer | Specify the number for read timeout in milliseconds. | 5 * 1000 | no |
| setMaxBatchSize | Integer | Specify the maximum request number per batch. Use a value from 1 to 10,000: a batch with more than 10,000 requests is discarded. For the FILE consumer, the library always uses 1. | 50 | no |
| setMaxQueueSize | Integer | Specify the maximum number of requests saved in each queue. When a queue reaches it, the queue is sent; if that fails, the oldest requests are discarded (logged at level WARN). `0` means unlimited. The cron job always uses an unlimited queue. | 1000 | no |
| setRequestInterval | Integer | Here you can define the interval in seconds at which the tracking requests should be sent automatically. If set to 0, no interval is started – sending the collected requests must then be triggered manually via flush (or happens when the instance is closed). | 0 | no |
| setRequestQueues | Integer | Here you can define the number of request queues to which the requests are to be distributed evenly (by everID, or by user agent and IP address). The library creates one additional fallback queue for requests without either, so the default results in 3 queues, each with its own background thread. | 2 | no |
| setMaxFileLines | Integer | The maximum number of lines per file (1 to 10,000). A larger value is reduced to 10,000 and logged at level WARN. | 10 * 1000 | no |
| setMaxFileDuration | Integer | The maximum file duration in milliseconds (1 to 30 * 60 * 1000). A larger value is reduced to the maximum and logged at level WARN. | 30 * 60 * 1000 | no |
| setMaxFileSize | Integer | The maximum file size in bytes (1 to 24 * 1024 * 1024). A larger value is reduced to the maximum and logged at level WARN. | 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. The library needs it for the default page name, for campaigns read from the URL (media codes) and for the include/exclude filters. An invalid URL is ignored. | empty | no |
| setCookie | Map<String, String> | Enter a map of all origin client cookies. The library reads the everID and the campaigns already transmitted in this session (once per session) from these cookies. | empty | no |
| addCookie | String | Enter a origin client cookie (key, value). | empty | no |

#### Notes

- **Include/exclude filters:** A request is measured if no include filter is set, or if at least one `containsInclude` string or `matchesInclude` expression matches the request URL. It is not measured if any `containsExclude` string or `matchesExclude` expression matches. The filters are only evaluated if a request URL is set, and they are evaluated when the tracking instance is created. Set the request URL and the filters before you create the instance.
- **Invalid values are ignored:** Setters with a value range keep their previous value if the new value is out of range, without a log entry. Setters that take an object or a list keep their previous value when called with `null`.
- **One configuration per request:** The configuration object is not thread-safe, and creating a tracking instance modifies it (for example, the FILE defaults are written into it). Build one configuration per request, or do not change a shared one while instances are created from it or still in use.

**Config File (properties)**

```java
MappIntelligenceConfig mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/properties/file/config.properties"
);
```

```java
# [tracking]
tracking.trackId=111111111111111
tracking.trackDomain=analytics01.wt-eu02.net
tracking.deactivate=false
tracking.domain=
tracking.logLevel=DEBUG
tracking.useParamsForDefaultPageName=
tracking.containsInclude=foo;bar
tracking.containsExclude=test
tracking.matchesInclude=.*foo.*;.*bar.*
tracking.matchesExclude=.*test.*

# [consumer]
consumer.consumerType=FILE
consumer.filePath=
consumer.filePrefix=
consumer.maxAttempt=1
consumer.attemptTimeout=100
consumer.maxBatchSize=50
consumer.maxQueueSize=1000
consumer.maxFileLines=10000
consumer.maxFileDuration=1800000
consumer.maxFileSize=25165824
```

**Config File (XML)**

```java
MappIntelligenceConfig mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/xml/file/config.xml"
);
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <!-- [tracking] -->
    <entry key="tracking.trackId">111111111111111</entry>
    <entry key="tracking.trackDomain">analytics01.wt-eu02.net</entry>
    <entry key="tracking.deactivate">false</entry>
    <entry key="tracking.domain" />
    <entry key="tracking.logLevel">DEBUG</entry>
    <entry key="tracking.useParamsForDefaultPageName" />
    <entry key="tracking.containsInclude">foo;bar</entry>
    <entry key="tracking.containsExclude">test</entry>
    <entry key="tracking.matchesInclude">.*foo.*;.*bar.*</entry>
    <entry key="tracking.matchesExclude">.*test.*</entry>

    <!-- [consumer] -->
    <entry key="consumer.consumerType">FILE</entry>
    <entry key="consumer.filePath" />
    <entry key="consumer.filePrefix" />
    <entry key="consumer.maxAttempt">1</entry>
    <entry key="consumer.attemptTimeout">100</entry>
    <entry key="consumer.maxBatchSize">50</entry>
    <entry key="consumer.maxQueueSize">1000</entry>
	<entry key="consumer.maxFileLines">10000</entry>
    <entry key="consumer.maxFileDuration">1800000</entry>
    <entry key="consumer.maxFileSize">25165824</entry>
</properties>
```

#### Using the configuration

Create one tracking instance per request and close it when the request is done (see [Lifecycle and Threading](/v1/docs/java-library#lifecycle-and-threading)):

```java
try (MappIntelligenceTracking tracking = new MappIntelligenceTracking(mappIntelligenceConfig)) {
    tracking.track(dataMap);
}
```

#### Notes on config files

- The path is a file system path, not a class path resource. A file whose name ends with `.xml` is read as XML properties file, every other file as `.properties` file. If the file cannot be found or read, no error is reported and the configuration keeps its defaults.
- Separate several values with a comma (`,`) in `tracking.domain` and `tracking.useParamsForDefaultPageName`, and with a semicolon (`;`) in `tracking.containsInclude`, `tracking.containsExclude`, `tracking.matchesInclude` and `tracking.matchesExclude`.
- Boolean values are only `true` if the value is exactly `true`. Integer values must consist of digits only, otherwise the default is used.
- `consumer.consumerType` only accepts `FILE` and `HTTP_CLIENT` (case-sensitive). Any other value, including `CUSTOM`, falls back to `HTTP_CLIENT`.
- The following options have no config file key and can only be set in code: `requestQueues`, `requestInterval`, `connectionTimeout`, `readTimeout`, `activateAdvancedPermission`, `advancedPermissionCategory`, `logger`, `consumer`, as well as the request data (`userAgent`, the client hints, `remoteAddress`, `referrerURL`, `requestURL`, `cookie`).