Integration and Configuration

Integration

Download

Download the Mapp Intelligence tracking library from our github repository mapp-digital/mapp-intelligence-tracking and add the tracking library in your PHP code:

use MappIntelligence\MappIntelligence;

Composer

$ composer require mapp-digital/mapp-intelligence-tracking

Configuration

Config Object

Methods

Config Array

Config File (ini)

$mappIntelligenceConfig = new MappIntelligenceConfig();
$mappIntelligenceConfig->setTrackId("111111111111111")
	->setTrackDomain("analytics01.wt-eu02.net")
	->setDomain(array())
	->addDomain("")
	->setUseParamsForDefaultPageName(array())
	->addUseParamsForDefaultPageName("")
    ->setActivateAdvancedPermission(false)
    ->setAdvancedPermissionCategory(0)

	->setContainsInclude(array())
	->addContainsInclude("")
	->setContainsExclude(array())
	->addContainsExclude("")
	->setMatchesInclude(array())
	->addMatchesInclude("")
	->setMatchesExclude(array())
	->addMatchesExclude("")

	->setLogger(null)
	->setLogLevel(MappIntelligenceLogLevel::ERROR)
	->setDebug(false)
	->setDeactivate(false)

	->setConsumerType("")
	->setConsumer(null)
	->setFilename("/tmp/MappIntelligenceRequests.log")
	->setFileMode("a")
	->setFilePath("/tmp/")
	->setFilePrefix("MappIntelligenceRequests")
	->setMaxAttempt(1)
	->setAttemptTimeout(100)
	->setMaxBatchSize(50)
	->setMaxQueueSize(1000)
	->setConnectionTimeout(30 * 1000)
	->setReadTimeout(5 * 1000)
	->setRequestInterval(0)
	->setMaxFileLines(10000)
    ->setMaxFileDuration(30 * 60 * 1000)
    ->setMaxFileSize(24 * 1024 * 1024)
	->setForceSSL(true)

	->setUserAgent("")
	->setClientHintUserAgent("")
	->setClientHintUserAgentFullVersionList("")
	->setClientHintUserAgentMobile("")
	->setClientHintUserAgentModel("")
	->setClientHintUserAgentPlatform("")
	->setClientHintUserAgentPlatformVersion("")
	->setRemoteAddress("")
	->setReferrerURL("")
	->setRequestURL("")
	->setCookie(array())
	->addCookie("", "");

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	String[]	Specify the domains you do not want to identify as an external referrer (e.g. your subdomains).	host of the request URL (with port, except 80 and 443), derived on every `build()`	no
addDomain	String	Specify the domain you do not want to identify as an external referrer (e.g. your subdomains).	empty	no
setUseParamsForDefaultPageName	String[]	Includes specific URL parameter(s) in the default page name.	empty	no
addUseParamsForDefaultPageName	String	Includes specific URL parameter(s) 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	0 (default): only Intelligence 3: Intelligence and Engage	0	no
setContainsInclude	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	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	String[]	Specify the regular expressions that must be match the request URL to measure the request.	empty	no
addMatchesInclude	String	Specify the regular expression that must be match the request URL to measure the request.	empty	no
setMatchesExclude	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).	null	no
setLogLevel	Integer or String	Specify the debug log level: 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 Use the constants of `MappIntelligenceLogLevel` or their names as string (case-insensitive). Other values are ignored.	ERROR	no
setDebug	Boolean	Activates the debug mode. The debug mode sends messages to the PHP system logger (Operating System's system logging mechanism or a file, depending on what the error_log configuration directive is set to).	false	no
setDeactivate	Boolean	Deactivate the tracking functionality.	false	no
setConsumerType	String	Specify the consumer to use for data transfer to Intelligence ( CURL, FORK_CURL, FILE, FILE_ROTATION or CUSTOM).	CURL	no
setConsumer	MappIntelligenceConsumer	Specify the custom consumer for data transfer to Intelligence (see MappIntelligenceConsumer).	null	no
setFilename	String	Enter the path to your request logging file. This is only relevant when using FILE consumer.	sys_get_temp_dir() . '/MappIntelligence Requests.log'	no
setFileMode	String	File mode of the FILE consumer: `a` (append) or `c`. `c` is treated like `a`, the requests are always appended. Other values are ignored silently.	a	no
setFilePath	String	Enter the path to your request logging file. This is only relevant when using FILE_ROTATION consumer.	sys_get_temp_dir() . '/'	no
setFilePrefix	String	Enter the prefix from your request logging files. This is only relevant when using FILE_ROTATION consumer.	MappIntelligenceRequests	no
setMaxAttempt	Integer	Specify the number of send attempts per flush (1 to 5, other values are ignored silently). If the last attempt fails, the requests stay in the queue and are sent again with the next `flush()` or `close()`; requests that are still queued when the instance is closed or destroyed are lost (e.g. CURL with a track server that cannot be reached). In the cron job they stay in the log file for the next run.	`1`	no
setAttemptTimeout	Integer	Specify the interval of request resend in milliseconds (1 to 500, other values are ignored silently).	100	no
setMaxBatchSize	Integer	Specify the maximum request number per batch. Values below 1 count as 1. A full batch is not sent right away: the requests are sent with `flush()`, `close()` or at the end of the request. There is no upper bound, but a batch with more than 10,000 requests is DISCARDED by the built-in consumers. Independent of this value, the queue ends a batch at about 20 MB request body. For the file consumers the value is always 1.	50	no
setMaxQueueSize	Integer	Specify the maximum number of requests saved in the queue. A full queue is sent first; if it is still full, the oldest requests are discarded with a warning. 0 means unlimited.	1000	no
setConnectionTimeout	Integer	Connection timeout of the HTTP consumer in milliseconds (0 = no timeout). Not used by FORK_CURL.	30 * 1000	no
setReadTimeout	Integer	Read timeout of the HTTP consumer in milliseconds (0 = no timeout). cURL has no pure read timeout, so the total time of a batch is limited to connection + read timeout; only if both values are greater than 0, otherwise the total time is not limited.	5 * 1000	no
setRequestInterval	Integer	Interval in seconds after which the queued requests are sent while new requests are added (0 = off, the requests are sent with `flush()`, `close()` or at the end of the request).	0	no
setRequestQueues	Integer	Number of request queues. Exists for compatibility with the Java library, PHP processes the requests of one instance in a single queue.	2	no
setMaxFileLines	Integer	The maximum number of lines per file. A larger value is reduced to the maximum (10 * 1000) with a warning.	10 * 1000	no
setMaxFileDuration	Integer	The maximum file duration in milliseconds. A larger value is reduced to the maximum (30 * 60 * 1000) with a warning.	30 * 60 * 1000	no
setMaxFileSize	Integer	The maximum file size in bytes. A larger value is reduced to the maximum (24 * 1024 * 1024) with a warning.	24 * 1024 * 1024	no
setForceSSL	Boolean	Sends every request via SSL.	true	no
setUserAgent	String	Enter the origin client HTTP user agent string.	$_SERVER['HTTP_USER_AGENT']	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).	$_SERVER['REMOTE_ADDR']	no
setReferrerURL	String	Enter the origin client HTTP referrer URL.	$_SERVER['HTTP_REFERER']	no
setRequestURL	String	Enter the origin client HTTP request URL. The protocol is taken from `$_SERVER['HTTPS']` or `$_SERVER['REQUEST_SCHEME']` (proxy headers like X-Forwarded-Proto are not evaluated, set the URL yourself behind a proxy).	$protocol . "://" . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']	no
setCookie	String[]	Enter a array of all origin client cookies.	$_COOKIE	no
addCookie	String	Enter a origin client cookie (key, value).	empty	no

Setters: null keeps the current value, every other value (also false, 0, "" and an empty list) is applied. A list setter (e.g. setDomain(array())) replaces the list, an add…() method appends to it. Exceptions: setters with a range (setMaxAttempt(), setAttemptTimeout(), setLogLevel(), setFileMode(), setConnectionTimeout(), setReadTimeout() and setRequestInterval() below 0, setMaxFile…() below 1) ignore a value outside of it, setRequestURL() ignores an invalid URL, setDebug(false) does not remove a logger that was set before.

Note
One configuration and one tracking instance per request: the configuration reads the request data (user agent, IP, cookies, request URL) from $_SERVER and $_COOKIE when it is built. In long-running PHP runtimes, create them for every request.

The constructor also accepts an array. Each key is the name of a setter without set, for example trackId for setTrackId() or maxBatchSize for setMaxBatchSize(). Keys without a matching setter are ignored. The key config loads a configuration file first; the other keys of the array are applied afterwards and overwrite its values.

$mappIntelligenceConfig = new MappIntelligenceConfig(array(
	"config" => "path/to/your/config/file/config.ini",
	"trackId" => "111111111111111",
	"trackDomain" => "analytics01.wt-eu02.net",
	"consumerType" => MappIntelligenceConsumerType::FILE_ROTATION,
	"filePath" => "/path/to/your/log/files/",
	"maxAttempt" => 3
));

You can also pass the array directly to new MappIntelligence(), MappIntelligence::getInstance() and new MappIntelligenceHybrid().

$mappIntelligenceConfig = new MappIntelligenceConfig(
	"path/to/your/config/file/config.ini"
);

[tracking]
trackId="111111111111111"
trackDomain="analytics01.wt-eu02.net"
deactivate=false
domain[]="sub.domain.tld"
useParamsForDefaultPageName[]="aa"
useParamsForDefaultPageName[]="bb"
useParamsForDefaultPageName[]="cc"
containsInclude[]=foo
containsInclude[]=bar
containsExclude[]=test
matchesInclude[]=/.*foo.*/
matchesInclude[]=/.*bar.*/
matchesExclude[]=/.*test.*/
; a list can also be one string: domain and useParamsForDefaultPageName are separated with ",",
; containsInclude, containsExclude, matchesInclude and matchesExclude with ";" (a regular expression may contain ",")
; domain = "sub.domain.tld, foo.bar"
; matchesExclude = "/.*test.*/;/\d{1,3}/"

[debugging]
debug=false
logLevel=DEBUG

[consumer]
consumerType="FILE_ROTATION"
filename=""
fileMode="a"
filePath=""
filePrefix=""
maxAttempt=1
attemptTimeout=100
maxBatchSize=50
maxQueueSize=1000
maxFileLines=10000
maxFileDuration=1800000
maxFileSize=25165824
forceSSL=true

Entries of a list in the config file are trimmed and empty entries are dropped. The consumer type is case-insensitive (consumerType = "file"), an unknown consumer type is ignored. A file that cannot be read or has a syntax error is ignored (defaults are used). Integer values must consist of digits only (no expressions such as 30 * 60 * 1000), otherwise the value is ignored. connectionTimeout, readTimeout, requestInterval, requestQueues, activateAdvancedPermission and advancedPermissionCategory are not read from the config file; set them with the setters or the config array.