--- title: "Classes" slug: "classes" description: "Reference of MappIntelligenceTracking and MappIntelligenceHybrid in the Java library: track, flush, close, cookies and a hybrid servlet example." status: "update" updated: 2026-11-02T16:46:50Z published: 2026-11-02T16:46:50Z canonical: "docs.mapp.com/classes" --- > ## 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. # Classes This section includes the available classes and examples. **MappIntelligenceTracking** ### Methods #### constructor For a complete configuration of the Mapp Intelligence Java library please check [Configuration](/v1/docs/integration-and-configuration). ```java /** * @param config Mapp Intelligence configuration */ MappIntelligenceTracking mappIntelligence = new MappIntelligenceTracking(MappIntelligenceConfig config); ``` #### track Requests are collected in internal queues and sent at defined intervals, via ***flush*** call or when the instance is closed (see ***close***). For a complete data configuration of the Mapp Intelligence Java library, please check [Data](/v1/docs/data). The return value is the ID of the request queue the request was added to (`0` to the value of `requestQueues`), or `-1` if the request was not added: tracking is deactivated, the track ID or track domain is missing, the include/exclude filters exclude the request URL, the data is `null`, or the instance is already closed. ```java /** * @return Integer Request queue ID */ mappIntelligence.track(); ``` ```java /** * @param data Mapp Intelligence parameter map * * @return Integer Request queue ID */ mappIntelligence.track(MappIntelligenceParameterMap data); ``` ```java /** * @param data Mapp Intelligence data map * * @return Integer Request queue ID */ mappIntelligence.track(MappIntelligenceDataMap data); ``` #### flush Here you can explicitly tell to send the data to the Mapp tracking servers. The call is best effort: it only hands the queued requests to the background threads and returns immediately, it does not wait until they are sent. Use ***close*** if the requests have to be handed to the consumer before you continue. After ***close***, `flush()` sends nothing and logs a warning. ```java /** * */ mappIntelligence.flush(); ``` #### setOnFlushComplete Here you can define a callback method that is automatically called after each ***flush***. The first argument is the status of the request dispatch. The second argument specifies which queue was involved. The status is also `false` if a batch of that queue was discarded because it can never be sent (for example a permanent client error). Besides ***flush***, the periodic flush of `requestInterval` and ***close*** call the callback as well. It runs on the background thread of the queue, so it must be thread-safe. ```java /** * @param callback Callback for complete flushing */ mappIntelligence.setOnFlushComplete(BiConsumer callback); ``` #### close Sends all remaining requests, waits up to 30 seconds for them to be handed to the consumer and releases the thread pools and the file handle of the file consumer. The call is idempotent; after it, `track` returns `-1` and requests are no longer accepted (each rejected request is logged at level ERROR). The 30 seconds are one deadline shared by all queues and include the retries (`maxAttempt` × `attemptTimeout`) and the time the consumer needs. If it expires, a warning is logged and the consumer is closed anyway; requests that are still being sent at that moment are lost. A consumer that you passed in via the configuration (`setConsumer`) is not closed by the library. An instance that is never closed sends its remaining requests only once it has been garbage collected or the JVM terminates, and there is no guarantee when that happens. ```java /** * */ mappIntelligence.close(); ``` ##### Example ```java try (MappIntelligenceTracking mappIntelligence = new MappIntelligenceTracking(mappConfig)) {    mappIntelligence.track(dataMap); } ``` #### 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](/v1/docs/integration-and-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](/v1/docs/interfaces)), which you then returned to the client. A cookie is only returned if the user has no everID yet; the library then generates one. Call the method before ***track***, so that the generated everID is also sent with the request. The method returns `null` if an everID already exists (from the cookies of the request), if the track ID or track domain is missing, if the pixel version is unknown (client side), or, with `MappIntelligence.SERVER_SIDE_COOKIE`, if the track domain is a Mapp domain (for example `*.wt-eu02.net`) instead of your own tracking domain. In the last two cases, an everID is still generated and sent with the requests. | Pixel version / context | Cookie name | Value | Domain | | --- | --- | --- | --- | | `SMART`, client side | `wtstp_eid` | the everID | – | | `V4` / `V5`, client side | `wt3_eid` | the existing `wt3_eid` value of the request plus `;<trackId>\|<everId>` | – | | any, `SERVER_SIDE_COOKIE` | `wteid_<trackId>` | the everID | the track domain without its first label (`track.example.com` becomes `example.com`) | All returned cookies have a max age of 180 days (15,552,000 seconds) and the path `/`, and they are always Secure and HttpOnly. ##### Options | MappIntelligence.V4 | pixelVersion | | --- | --- | | MappIntelligence.V5 | pixelVersion | | MappIntelligence.SMART | pixelVersion | | MappIntelligence.CLIENT_SIDE_COOKIE | context | | MappIntelligence.SERVER_SIDE_COOKIE | context | ```java /** * @param pixelVersion Version ot the current pixel (v4, v5, smart) * @param context Cookie context (1, 3) * * @return MappIntelligenceCookie */ MappIntelligenceCookie mappCookie = mappIntelligence.getUserIdCookie(String pixelVersion, String context); ``` #### getTransmittedCampaignsCookie Required if you use `MappIntelligenceCampaign.setOncePerSession(true)` (see [Campaign](/v1/docs/campaign-data-object-java-library-s2s)). The library remembers the campaigns already transmitted in this session in the cookie `wtstp_tcc`. The method returns this cookie (see [MappIntelligenceCookie](/v1/docs/interfaces)) after a new campaign was transmitted, otherwise `null`. You have to add it to the HTTP response yourself, before the response is committed, otherwise "once per session" cannot work across requests. The cookie is a session cookie (max age `-1`) with the path `/`, not HttpOnly (the pixel reads it as well), and secure unless the request URL is plain HTTP. Only `track(MappIntelligenceDataMap)` with a campaign object evaluates "once per session"; a request sent with a `MappIntelligenceParameterMap` never changes the cookie. ```java /** * @return MappIntelligenceCookie or null */ MappIntelligenceCookie campaignsCookie = mappIntelligence.getTransmittedCampaignsCookie(); ``` ##### Example ```java MappIntelligenceCookie campaigns = mappIntelligence.getTransmittedCampaignsCookie(); if (campaigns != null) {    Cookie cookie = new Cookie(campaigns.getName(), campaigns.getValue());    cookie.setPath(campaigns.getPath());    cookie.setSecure(campaigns.isSecure());    cookie.setHttpOnly(campaigns.isHttpOnly());    cookie.setMaxAge(campaigns.getMaxAge());    response.addCookie(cookie); } ``` **MappIntelligenceHybrid** ### Methods #### constructor For a complete configuration of the Mapp Intelligence Hybrid please check [Configuration](/v1/docs/integration-and-configuration). The hybrid writes the requests into log files that you send with the [Cron Job](/v1/docs/cron-job): the constructor sets the consumer type of the configuration that you pass in to `FILE`, unless it is `CUSTOM`. This changes your configuration object: `maxBatchSize` becomes 1, and `filePath` and `filePrefix` get their defaults if they are empty. ```java /** * @param config Mapp Intelligence configuration */ MappIntelligenceHybrid mappIntelligenceHybrid = new MappIntelligenceHybrid(MappIntelligenceConfig config); ``` #### track Reads all query parameters from the current request URL (see `setRequestURL` in [Configuration](/v1/docs/integration-and-configuration)) and saves the request in the internal queues, which are sent at defined intervals, via ***flush*** call or when the instance is closed. The return value is the request queue ID, or `-1` if nothing was added. - Only pixel requests are accepted: the query string has to contain the pixel parameter `p` with a value and may be at most 64 KB (see ***isValidPixelRequest***). Any other request is ignored (logged at level WARN) instead of being written into the log files. - The parameters that only the server may set are removed from the client request first: `X-WT-IP`, `X-WT-UA` and `X-WT-SEC-CH-UA*`, so a client cannot pretend to be another user. The library then adds user agent, IP address and client hints from the configuration, if they are set there. - `track(String rURL)` with a malformed URL or `null` does not track anything and returns `-1`. The previous request URL is not tracked again. - Unlike `MappIntelligenceTracking`, the hybrid does not add the everID (`eid`), because the pixel requests carry their own. It also does not check the track ID or track domain and does not apply the include/exclude filters. ```java mappIntelligenceHybrid.track(); ``` ```java /** * @param rURL request url with query parameters */ mappIntelligenceHybrid.track(String rURL); ``` #### isValidPixelRequest Checks whether a query string is accepted by ***track***: it must not be `null`, must contain the pixel parameter `p` with a value (`p=...`) and may be at most 64 KB (65,536 bytes, measured in UTF-8). ```java /** * @param queryString Query string of the pixel request * * @return true if the query string contains the pixel parameter "p" and is not too long */ boolean valid = MappIntelligenceHybrid.isValidPixelRequest(String queryString); ``` #### flush Here you can explicitly tell to send the data to the Mapp tracking servers. ```java /** * */ mappIntelligenceHybrid.flush(); ``` #### setOnFlushComplete Here you can define a callback method that is automatically called after each ***flush***. The first argument is the status of the request dispatch. The second argument specifies which queue was involved. ```java /** * @param callback Callback for complete flushing */ mappIntelligenceHybrid.setOnFlushComplete(BiConsumer callback); ``` #### close Same as `MappIntelligenceTracking.close()`: sends the remaining requests, waits up to 30 seconds (one deadline for all queues) for them to be handed to the consumer, releases thread pools and file handles, and is idempotent. Use one instance per request with try-with-resources (see the example below). ```java /** * */ mappIntelligenceHybrid.close(); ``` #### getUserIdCookie Returns the same cookies as `MappIntelligenceTracking.getUserIdCookie()` (see the MappIntelligenceTracking tab), so a user without everID gets one. The generated everID is not added to the requests of the hybrid, because the requests forwarded from the pixel carry their own `eid`. ```java /** * @param pixelVersion Version ot the current pixel (v4, v5, smart) * @param context Cookie context (CLIENT_SIDE_COOKIE = "1", SERVER_SIDE_COOKIE = "3") * * @return MappIntelligenceCookie */ MappIntelligenceCookie mappCookie = mappIntelligenceHybrid.getUserIdCookie(String pixelVersion, String context); ``` > [!NOTE] > Note > > `getTransmittedCampaignsCookie()` is also available on `MappIntelligenceHybrid`, but it always returns `null` there: the hybrid forwards the pixel requests unchanged and does not evaluate campaigns. #### getResponseAsString As response, the method returns a 1x1px transparent gif, which you then returned to the client. ```java /** * @return Returns a 1x1px transparent gif as string. */ String imageString = mappIntelligenceHybrid.getResponseAsString(); ``` > [!NOTE] > Note > > The string is created from the GIF bytes with the platform default charset, so it does not reliably contain the original bytes. To send the image to the client, use ***getResponseAsBytes***. #### getResponseAsBytes As response, the method returns a 1x1px transparent gif, which you then returned to the client. ```java /** * @return Returns a 1x1px transparent gif as byte array. */ byte[] imageBytes = mappIntelligenceHybrid.getResponseAsBytes(); ``` #### Example ```java package demo.servlets; import com.mapp.intelligence.tracking.MappIntelligence; import com.mapp.intelligence.tracking.MappIntelligenceCookie; import com.mapp.intelligence.tracking.config.MappIntelligenceConfig; import com.mapp.intelligence.tracking.core.MappIntelligenceHybrid; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.Cookie; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.io.OutputStream; @WebServlet("/pix/*") public class TrackingServlet extends HttpServlet {    public TrackingServlet() {        super();    }    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {        // set tracking configuration        MappIntelligenceConfig mappConfig = new MappIntelligenceConfig()            .setTrackId("111111111111111")            .setTrackDomain("analytics01.wt-eu02.net")            .setReferrerURL(request.getHeader("Referer"))            // with the query string: the hybrid forwards the query parameters of the pixel request            .setRequestURL(request.getRequestURL() + (request.getQueryString() != null ? "?" + request.getQueryString() : ""))            .setRemoteAddress(request.getRemoteAddr())            .setUserAgent(request.getHeader("User-Agent"));        // read out all client cookies and add them to the configuration        Cookie[] cookies = request.getCookies();        if (cookies != null) {            for (Cookie cookie : cookies) {                mappConfig.addCookie(cookie.getName(), cookie.getValue());            }        }        // the instance carries the data of this request, so it is created and closed per request;        // close() sends the remaining requests        try (MappIntelligenceHybrid mappHybrid = new MappIntelligenceHybrid(mappConfig)) {            // writes the incoming request to the Mapp Intelligence request queue            mappHybrid.track();            byte[] imgBytes = mappHybrid.getResponseAsBytes();            // set content-type and length            response.setContentType("image/gif");            response.setContentLength(imgBytes.length);            // read out the existing Mapp Intelligence user cookie            MappIntelligenceCookie mappUserCookie = mappHybrid.getUserIdCookie(MappIntelligence.SMART, MappIntelligence.CLIENT_SIDE_COOKIE);            if (mappUserCookie != null) {                // create a cookie                Cookie mappUserCookieResponse = new Cookie(mappUserCookie.getName(), mappUserCookie.getValue());                mappUserCookieResponse.setHttpOnly(mappUserCookie.isHttpOnly());                mappUserCookieResponse.setSecure(mappUserCookie.isSecure());                // the v4 and smart pixel cookies have no domain (empty string)                if (!mappUserCookie.getDomain().isEmpty()) {                    mappUserCookieResponse.setDomain(mappUserCookie.getDomain());                }                mappUserCookieResponse.setPath(mappUserCookie.getPath());                mappUserCookieResponse.setMaxAge(mappUserCookie.getMaxAge());                // add the cookie to the response                response.addCookie(mappUserCookieResponse);            }            // send a 1x1 pixel transparent gif back to the client, unchanged            OutputStream out = response.getOutputStream();            out.write(imgBytes);        }    }    protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {        this.doGet(request, response);    } } ``` ## Further Classes ### MappIntelligenceParameter Package `com.mapp.intelligence.tracking`. Constants with the names of all request parameters, for example `MappIntelligenceParameter.PAGE_NAME` (`pn`) or `MappIntelligenceParameter.ORDER_VALUE` (`ov`). Use them with a `MappIntelligenceParameterMap` (see [Request Parameters](/v1/docs/request-parameters-data-object-java-library-s2s)). In addition, the class contains the prefixes of the numbered custom parameters and the cookie names: | Name | Value | Description | | --- | --- | --- | | CUSTOM_SESSION_PARAMETER | `cs` | Prefix of session parameters. | | CUSTOM_PAGE_PARAMETER | `cp` | Prefix of page parameters. | | CUSTOM_PRODUCT_PARAMETER | `cb` | Prefix of E-Commerce Parameters (product, order, goals). | | CUSTOM_ACTION_PARAMETER | `ck` | Prefix of event parameters. | | CUSTOM_CAMPAIGN_PARAMETER | `cc` | Prefix of campaign parameters. | | CUSTOM_REGISTRATION_PARAMETER | `er` | Prefix of the Mapp Engage registration parameters. | | CUSTOM_PAGE_CATEGORY | `cg` | Prefix of page categories. | | CUSTOM_PRODUCT_CATEGORY | `ca` | Prefix of product categories. | | CUSTOM_URM_CATEGORY | `uc` | Prefix of user (URM) categories. | | SMART_PIXEL_COOKIE_NAME | `wtstp_eid` | everID cookie of the Smart Pixel. | | TRANSMITTED_CAMPAIGNS_COOKIE_NAME | `wtstp_tcc` | Cookie with the campaigns already transmitted in this session. | | PIXEL_COOKIE_NAME | `wt3_eid` | everID cookie of pixel v4/v5. | | SERVER_COOKIE_NAME_PREFIX | `wteid_` | Prefix of the server-side everID cookie (`wteid_<trackId>`). | ### MappIntelligenceCustomParameter Package `com.mapp.intelligence.tracking`. Enum to build the names of numbered custom parameters. The constants are `CUSTOM_SESSION_PARAMETER`, `CUSTOM_PAGE_PARAMETER`, `CUSTOM_PRODUCT_PARAMETER`, `CUSTOM_ACTION_PARAMETER`, `CUSTOM_CAMPAIGN_PARAMETER`, `CUSTOM_REGISTRATION_PARAMETER`, `CUSTOM_PAGE_CATEGORY`, `CUSTOM_PRODUCT_CATEGORY`, `CUSTOM_URM_CATEGORY` (prefixes as in the table above). #### with ```java /** * @param id ID of the custom parameter * * @return String e.g. "cp5" for CUSTOM_PAGE_PARAMETER.with(5) */ String name = MappIntelligenceCustomParameter.CUSTOM_PAGE_PARAMETER.with(int id); ``` ### MappIntelligenceLogLevel Package `com.mapp.intelligence.tracking`. Constants for `MappIntelligenceConfig.setLogLevel(int)`: `NONE` = 0, `FATAL` = 1, `ERROR` = 2 (default), `WARN` = 3, `INFO` = 4, `DEBUG` = 5. A level shows all messages of that level and of the levels with a lower number. #### getName ```java /** * @param ll Integer log level * * @return Log level name, e.g. "ERROR", or null for an unknown value */ String name = MappIntelligenceLogLevel.getName(int ll); ``` #### getValue ```java /** * @param ll Log level name (case-insensitive) * * @return int Integer log level, -1 for an unknown name or null */ int value = MappIntelligenceLogLevel.getValue(String ll); ``` ### AbstractMappIntelligenceData Package `com.mapp.intelligence.tracking.data`. Base class of all data objects (`MappIntelligencePage`, `MappIntelligenceAction`, …). Its methods are useful for debugging. #### getData ```java /** * @return Map(String, Object) All fields of the data object, including unset ones */ Map data = mappPageData.getData(); ``` #### getQueryParameter ```java /** * @return Map(String, String) The request parameters the object produces */ Map queryParameter = mappPageData.getQueryParameter(); ``` For a campaign, `getQueryParameter()` contains only the explicitly set ID. The media codes of the request URL and once per session are resolved by `track()`. ### MappIntelligenceConsumerHttpClient and MappIntelligenceConsumerFile Package `com.mapp.intelligence.tracking.consumer`. The built-in consumers for the consumer types `HTTP_CLIENT` and `FILE` (see [Data Transfer: Consumer](/v1/docs/data-transfer-consumer)). The library creates them itself. Create one yourself only to extend it or to share one instance via `setConsumer`. A consumer that you create yourself has to be closed by you. ```java /** * @param config Mapp Intelligence configuration, e.g. mappIntelligenceConfig.build() */ MappIntelligenceConsumerHttpClient httpConsumer = new MappIntelligenceConsumerHttpClient(Map config); MappIntelligenceConsumerFile fileConsumer = new MappIntelligenceConsumerFile(Map config); ``` #### setOnSessionId `MappIntelligenceConsumerHttpClient` only. Optional callback that receives the ID of the TLS session the batch was sent over, after each batch. It is called from the queue threads, so it must be thread-safe. ```java /** * @param callback Receiver of the TLS session ID */ httpConsumer.setOnSessionId(Consumer callback); ``` ### ###