Classes

This section includes the available classes with examples.

MappIntelligence

MappIntelligenceHybrid

MappIntelligenceDataMap

MappIntelligenceProductCollection

MappIntelligenceParameterMap

Methods

constructor

Creates a tracking instance. The instance carries the data of the current HTTP request (user agent, IP, cookies, ever ID), so create one instance per request and close it. This is required in long-running PHP runtimes (RoadRunner, Swoole, FrankenPHP worker mode, Laravel Octane), where static state survives the request. For a complete configuration of the Mapp Intelligence PHP library please check Configuration.

/**
 * @param MappIntelligenceConfig|array|string $config Config object, config array or path to a config file
 */
$mappIntelligence = new MappIntelligence($config);

getInstance

Returns the shared Mapp Intelligence instance of the current PHP process. The configuration is only used for the first call. In long-running PHP runtimes call reset() at the end of every request or use one new MappIntelligence($config) per request.

/**
 * @param MappIntelligenceConfig $config
 * @return MappIntelligence
 */
$mappIntelligence = MappIntelligence::getInstance($config);

reset

Closes the shared instance of getInstance() (the remaining requests are sent). The next getInstance() call creates a new instance with the data of the current request.

MappIntelligence::reset();

track

Sends the data to the Mapp track server. For a complete data configuration of the Mapp Intelligence PHP library, please check Data.

Without data, a page request with the default page name is tracked. The request is queued and sent with flush(), close() or at the end of the request (with requestInterval also while requests are added). After close() the request is rejected.

/**
 * @param MappIntelligenceParameterMap|MappIntelligenceDataMap|array $data
 * @return bool false if the request was not added (tracking deactivated, instance closed)
 */
$mappIntelligence->track($data);

flush

Here you can explicitly send the data to the Mapp tracking servers. In most configurations this is done automatically by the PHP runtime environment. Just to be sure, you should call this manually at the end of your script.

/**
 * @return boolean true if every request was delivered, false if requests are still queued or were discarded
 */
$mappIntelligence->flush();

close

Sends the remaining requests and releases the consumer (HTTP connection, file handle). Afterwards track() is rejected. close() is called automatically when the instance is destroyed; calling it again has no effect.

/**
 * @return boolean true if no request remains unsent
 */
$mappIntelligence->close();

setOnFlushComplete

The callback is called after every flush with true if all requests were delivered.

/**
 * @param callable|null $callback function (bool $success)
 * @return MappIntelligence
 */
$mappIntelligence->setOnFlushComplete(function ($success) {
    // ...
});

getTransmittedCampaignsCookie

Returns the cookie with the campaigns already transmitted in this session (campaigns with "once per session", see Campaign), or null if nothing changed. Add it to the HTTP response, otherwise "once per session" cannot work across requests. It is a session cookie and deliberately not HttpOnly, because the client-side pixel reads the same cookie.

/**
 * @return MappIntelligenceCookie|null
 */
$cookie = $mappIntelligence->getTransmittedCampaignsCookie();
if ($cookie) {
    setcookie($cookie->getName(), $cookie->getValue(), 0, $cookie->getPath(), $cookie->getDomain(),
        $cookie->isSecure(), $cookie->isHttpOnly());
}

getUserIdCookie

It is important to uniquely identify a user to fully benefit from Mapp Intelligence tracking capabilities. Mapp Intelligence uses the everID (eid) internally to keep the tracking information aligned to a user. You can either pass your own unique identifier or you can use the library to use an existing everID (see Configuration → setCookie). If you track with both the server-side library and the pixel and you use the getUserIdCookie() method, an eid cookie is returned (see MappIntelligenceCookie), which you then returned to the client. The method only returns the cookie, it does not send it: add it to the HTTP response yourself. getMaxAge() is the maximum age in seconds (180 days); for setcookie() use time() + $cookie->getMaxAge() as expiry (see MappIntelligenceCookie).

null is returned if

an everID already exists (from the cookies of the request or from an earlier call),
the context is SERVER_SIDE_COOKIE and the track domain is a Mapp track domain (*.wt-*.net, *.webtrekk.net, *.webtrekk-*.net): a server-side cookie requires your own track domain,
the context is CLIENT_SIDE_COOKIE and the pixel version is not V4, V5 or SMART,
the track ID or the track domain is not configured (logged as ERROR).

In the second and third case, a new everID is still created and used for the requests of this instance. Pass the context as the constants (strings '1' and '3'); it is compared strictly.

Options

MappIntelligence::V4	pixelVersion
MappIntelligence::V5	pixelVersion
MappIntelligence::SMART	pixelVersion
MappIntelligence::CLIENT_SIDE_COOKIE	context
MappIntelligence::SERVER_SIDE_COOKIE	context

/**
 * @param string $pixelVersion Version ot the current pixel (v4, v5, smart)
 * @param string $context Cookie context (1, 3)
 *
 * @return MappIntelligenceCookie
 */
$mappIntelligence->getUserIdCookie($pixelVersion, $context);

setUserId

It is important to uniquely identify a user to fully benefit from Mapp Intelligence tracking capabilities. Mapp Intelligence uses the everID (eid) internally to keep the tracking information aligned to a user. You can either pass your own unique identifier or you can use the library to create it using the setUserId() method. If you track with both the server-side library and the pixel and you use the setUserId() method it will not override the everID (eid) of the pixel. This is only generated if no eid exists yet. Unlike getUserIdCookie(), setUserId() sends the cookie itself (setcookie()). If no cookie is created, nothing is sent.

Options

MappIntelligence::V4	pixelVersion
MappIntelligence::V5	pixelVersion
MappIntelligence::SMART	pixelVersion
MappIntelligence::CLIENT_SIDE_COOKIE	context
MappIntelligence::SERVER_SIDE_COOKIE	context

/**
 * @param string $pixelVersion Version of the current pixel (v4, v5, smart)
 * @param string $context Cookie context (1, 3)
 *
 * @return bool false if the track ID or the track domain is missing
 */
$mappIntelligence->setUserId($pixelVersion, $context);

Methods

constructor

For a complete configuration of the Mapp Intelligence Hybrid please check Configuration.

The hybrid only writes the pixel requests to files, the cron job sends them. The consumer types FILE_ROTATION and CUSTOM are used as configured; every other consumer type (CURL, FORK_CURL and the default) is replaced by FILE.

/**
 * @param MappIntelligenceConfig|array $config Mapp Intelligence configuration
 */
$mappIntelligenceHybrid = new MappIntelligenceHybrid($config);

setRequestURL

If the query parameters from the current request are not in $_SERVER['QUERY_STRING'], please set them before calling run (or pass the URL to track).

/**
 * @param string $rURL HTTP request url with query parameters
 * @return bool false if the URL is invalid (the current request URL is kept)
 */
$mappIntelligenceHybrid->setRequestURL($rURL);

run

Reads all query parameters from the current request and saves them in the file. As default response, the method returns a 1x1px transparent gif. Only pixel requests with the parameter p and at most 64 KB are written into the log file (see track).

/**
 * @param bool $withoutResponse
 */
$mappIntelligenceHybrid->run($withoutResponse);

track

Reads all query parameters of the pixel request and saves them in the file (without sending a response). Only pixel requests with the parameter p and at most 64 KB are accepted (otherwise WARN); the endpoint is public and must not fill the disk. The parameters that only the server adds (X-WT-IP, X-WT-UA, X-WT-SEC-CH-UA*) are removed from the request of the client, so a client cannot pretend to be another user; the library adds them from the configuration. An invalid URL returns false and tracks nothing (the previous request is not tracked again).

/**
 * @param string|null $rURL Pixel request URL with query parameters, default is the current request
 * @return bool false if the URL is invalid, there is nothing to track, the tracking is deactivated or the request is no valid pixel request
 */
$mappIntelligenceHybrid->track($rURL);

flush, close, setOnFlushComplete, getUserIdCookie

Work like the methods of MappIntelligence. getTransmittedCampaignsCookie() always returns null, campaigns are resolved by the client-side pixel in the hybrid mode.

getResponseAsBytes

Returns the 1x1px transparent gif as binary string (same as getResponseAsImage).

$bytes = $mappIntelligenceHybrid->getResponseAsBytes();

getResponseAsImage

As response, the method returns a 1x1px transparent gif, which you then returned to the client.

/**
 * @return Returns a 1x1px transparent gif as image.
 */
$image = $mappIntelligenceHybrid->getResponseAsImage();

getResponseAsBase64

As response, the method returns a 1x1px transparent gif, which you then returned to the client.

/**
 * @return Returns a 1x1px transparent gif as base64.
 */
$imageBase64 = $mappIntelligenceHybrid->getResponseAsBase64();

Example

require_once __DIR__ . '/vendor/autoload.php';

use MappIntelligence\MappIntelligenceHybrid;
use MappIntelligence\Config\MappIntelligenceConfig;

try {
    $mappIntelligenceConfig = new MappIntelligenceConfig('./config.ini');
    $mappHybrid = new MappIntelligenceHybrid($mappIntelligenceConfig);
    $mappHybrid->run();
} catch (Exception $e) {
    error_log($e->getMessage());
}

Methods

constructor

/**
 *
 */
$mappIntelligenceDataMap = new MappIntelligenceDataMap();

action

/**
 * @param MappIntelligenceAction $data Mapp Intelligence action data
 * @return $this
 */
$mappIntelligenceDataMap->action($data);

campaign

/**
 * @param MappIntelligenceCampaign $data Mapp Intelligence campaign data
 * @return $this
 */
$mappIntelligenceDataMap->campaign($data);

customer

/**
 * @param MappIntelligenceCustomer $data Mapp Intelligence customer data
 * @return $this
 */
$mappIntelligenceDataMap->customer($data);

order

/**
 * @param MappIntelligenceOrder $data Mapp Intelligence order data
 * @return $this
 */
$mappIntelligenceDataMap->order($data);

page

/**
 * @param MappIntelligencePage $data Mapp Intelligence page data
 * @return $this
 */
$mappIntelligenceDataMap->page($data);

product

/**
 * @param MappIntelligenceProductCollection $data Mapp Intelligence product collection
 * @return $this
 */
$mappIntelligenceDataMap->product($data);

session

/**
 * @param MappIntelligenceSession $data Mapp Intelligence session data
 * @return $this
 */
$mappIntelligenceDataMap->session($data);

registration

/**
 * @param MappIntelligenceRegistration $data Mapp Engage registration data (User Matching)
 * @return $this
 */
$mappIntelligenceDataMap->registration($data);

engage

/**
 * @param MappIntelligenceEngage $data Mapp Engage data (custom attributes, custom web event)
 * @return $this
 */
$mappIntelligenceDataMap->engage($data);

For both, see Mapp Engage.

Example

$mappIntelligence = MappIntelligence::getInstance();
$page = new MappIntelligencePage('en.page.test');
$page->setCategory(1, 'page.test')
	->setCategory(2, 'en')
	->setCategory(3, 'page')
	->setCategory(4, 'test');

$session = new MappIntelligenceSession();
$session->setParameter(1, '1');

$customer = new MappIntelligenceCustomer('24');
$customer->setFirstName('John')
	->setLastName('Doe')
	->setEmail('john@doe.com');

$product1 = new MappIntelligenceProduct('065ee2b001');
$product1->setCost(59.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product2 = new MappIntelligenceProduct('085eo2f009');
$product2->setCost(49.99)
	->setQuantity(5)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product3 = new MappIntelligenceProduct('995ee1k906');
$product3->setCost(15.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product4 = new MappIntelligenceProduct('abc');
$product4->setCost(0)
	->setQuantity(0)
	->setSoldOut(true)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$products = new MappIntelligenceProductCollection();
$products->add($product1)
	->add($product2)
	->add($product3)
	->add($product4);

$mappIntelligence->track((new MappIntelligenceDataMap)
	->page($page)
	->order(new MappIntelligenceOrder(360.93))
	->session($session)
	->customer($customer)
	->product($products)
);

Methods

constructor

/**
 *
 */
$mappIntelligenceProductCollection = new MappIntelligenceProductCollection();

add

/**
 * @param MappIntelligenceProduct $product Mapp Intelligence product data
 * @return $this
 */
$mappIntelligenceProductCollection->add($product);

Example

$mappIntelligence = MappIntelligence::getInstance();
$product1 = new MappIntelligenceProduct('065ee2b001');
$product1->setCost(59.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product2 = new MappIntelligenceProduct('085eo2f009');
$product2->setCost(49.99)
	->setQuantity(5)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product3 = new MappIntelligenceProduct('995ee1k906');
$product3->setCost(15.99)
	->setQuantity(1)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$product4 = new MappIntelligenceProduct('abc');
$product4->setCost(0)
	->setQuantity(0)
	->setSoldOut(true)
	->setStatus(MappIntelligenceProduct::CONFIRMATION);

$products = new MappIntelligenceProductCollection();
$products->add($product1)
	->add($product2)
	->add($product3)
	->add($product4);

$mappIntelligence->track((new MappIntelligenceDataMap)
	->product($products)
);

Methods

constructor

/**
 *
 */
$mappIntelligenceParameterMap = new MappIntelligenceParameterMap();

add

/**
 * @param string $key Add key to map
 * @param string $value Add value to map
 * @return $this
 */
$mappIntelligenceParameterMap->add($key, $value);

Example

$mappIntelligence = MappIntelligence::getInstance();

$mappIntelligenceParameterMap = new MappIntelligenceParameterMap();
$mappIntelligenceParameterMap
	->add(MappIntelligenceParameter::$PAGE_NAME, 'en.page.test')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(1), 'page.test')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(2), 'en')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(3), 'page')
	->add(MappIntelligenceCustomParameter::$CUSTOM_PAGE_CATEGORY->with(4), 'test')
	->add(MappIntelligenceParameter::$ORDER_VALUE, 360.93)
	->add(MappIntelligenceParameter::$CUSTOMER_ID, '24')
	->add(MappIntelligenceParameter::$FIRST_NAME, 'John')
	->add(MappIntelligenceParameter::$LAST_NAME, 'Doe')
	->add(MappIntelligenceParameter::$EMAIL, 'john@doe.com')
	->add(MappIntelligenceParameter::$PRODUCT_ID, '065ee2b001;085eo2f009;995ee1k906')
	->add(MappIntelligenceParameter::$PRODUCT_COST, '59.99;49.99;15.99')
	->add(MappIntelligenceParameter::$PRODUCT_QUANTITY, '1;5;1')
	->add(MappIntelligenceParameter::$PRODUCT_STATUS, 'conf');

$mappIntelligence->track($mappIntelligenceParameterMap);