Integration and Configuration

Updated
  • 8 minute(s) read
Prev Next

Integration

Maven

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

Gradle

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

Configuration

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

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). 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). 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 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).

HTTP_CLIENT

no

setConsumer

MappIntelligenceConsumer

Specify the custom consumer to use for data transfer to Intelligence (see MappIntelligenceConsumer). 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.

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? and 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? and 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? and 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? and 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? and 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? and 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.

MappIntelligenceConfig mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/properties/file/config.properties"
);
# [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
MappIntelligenceConfig mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/xml/file/config.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):

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).