Classes

Methods

constructor

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

/**
 * @param config Mapp Intelligence configuration
 */
const mappIntelligence = new MappIntelligenceTracking(config: MappIntelligenceConfig);

track

Adds the data to the request queue. Adding sends nothing: the queue is sent via flush(), every requestInterval seconds, when it reaches maxQueueSize or when the instance is closed (see close). For a complete data configuration of the Mapp Intelligence js library, please check Data.

The promise resolves to false if the data was not added (tracking deactivated, track ID or track domain missing, tracking deactivated by the include/exclude configuration, unsupported data or the instance is already closed). After close(), the request is logged at level ERROR: Request rejected, the tracking instance is already closed: <request>.

/**
 * @param [data] Mapp Intelligence parameter or data map
 *
 * @return Promise<boolean>
 */
mappIntelligence.track(data?: MappIntelligenceParameterMap | MappIntelligenceDataMap);

flush

Sends all requests in the queue to the Mapp tracking servers. The promise resolves to true if everything was delivered, and to false if requests are still in the queue or a batch was discarded. Flushes run one after another: a flush that starts while another one is running waits for it and then sends what is left.

After close(), flush() sends nothing: it logs Flush ignored, the tracking instance is already closed. at level WARN, calls the setOnFlushComplete callback and resolves to true if the queue is empty.

/**
 * @return Promise<boolean>
 */
await mappIntelligence.flush();

setOnFlushComplete

Here you can define a callback that is called after each flush with the result of the flush (true if everything was delivered). It is called for flush(), for the flush of requestInterval, for the flush when the queue reaches maxQueueSize and for close(). The result is false as well if a batch was discarded (see Data Transfer: Consumer). A callback that throws is logged at level ERROR.

A callback that references the tracking instance keeps it reachable: an instance that is never closed is then not cleaned up after garbage collection.

/**
 * @param callback Callback after every flush, with the result of the flush
 */
mappIntelligence.setOnFlushComplete((wasRequestSuccessful: boolean) => {});

close

Sends the remaining requests and releases the consumer. Afterwards every track() call is rejected (see above). The promise resolves to true if no request remains unsent and no batch was discarded.

• close() waits for flushes that are still running, but at most 30 seconds, including the retries (maxAttempt × attemptTimeout) and the time the consumer needs. If the time expires, Timeout after 30000 ms while waiting for the queue to be flushed, ... is logged at level WARN and the promise resolves to false; the last batch is still sent in the background.

• close() is idempotent: every call returns the result of the first one.

• A consumer that you passed in via the configuration (setConsumer) is not closed by the library.

• If the process ends with requests that were never sent (e.g. process.exit() without close()), The process ends with <n> unsent req. in the queue, call close() before the process ends. is logged at level ERROR.

/**
 * @return Promise<boolean>
 */
await mappIntelligence.close();

Example

app.get('/product', async function(request, response) {
    // a new configuration per request, so no request data of a previous user is kept
    const mappConfig = new MappIntelligenceConfig('111111111111111', 'analytics01.wt-eu02.net')
        .setRequestURL('https://' + request.headers['host'] + request.url)
        .setReferrerURL(request.headers['referer'])
        .setUserAgent(request.headers['user-agent'])
        .setRemoteAddress(request.socket.remoteAddress);

    const mappIntelligence = new MappIntelligenceTracking(mappConfig);
    try {
        await mappIntelligence.track(new MappIntelligenceDataMap().page(new MappIntelligencePage('en.product')));
    } finally {
        await mappIntelligence.close();
    }

    response.send('...');
});

getTransmittedCampaignsCookie

Returns the cookie wtstp_tcc with the campaigns that were already transmitted in this session, or null if nothing changed. Add it to the HTTP response, otherwise MappIntelligenceCampaign.setOncePerSession(true) cannot work across requests (see Campaign). It is a session cookie (getMaxAge() returns -1), not HttpOnly (the client-side pixel reads it as well) and Secure unless the request URL uses plain HTTP. The value is URL encoded and keeps the newest campaigns within 4000 characters.

/**
 * @return IMappIntelligenceCookie
 */
const campaignCookie = mappIntelligence.getTransmittedCampaignsCookie();

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 IMappIntelligenceCookie), which you then returned to the client.

If no everID exists yet, getUserIdCookie() creates one, and every request that is added afterwards contains it (eid). Call it before track(): requests that are already in the queue do not get the everID.

The method returns null:

• without track ID or track domain (logged at level ERROR); no everID is created,

• if an everID already exists: read from the cookies of the configuration (wtstp_eid, wteid_<trackId> or wt3_eid, see setCookie()) or created by an earlier call,

• with SERVER_SIDE_COOKIE and a Mapp track domain (*.wt-*.net, *.webtrekk.net, *.webtrekk-*.net): the cookie can only be set for your own track domain,

• with CLIENT_SIDE_COOKIE and a pixel version other than V4, V5 or SMART.

In the last two cases the everID is still created and added to the following requests.

Every returned cookie has the path /, a max age of 6 months (in seconds) and is Secure and HttpOnly.

Options

/**
 * @param pixelVersion Version ot the current pixel (v4, v5, smart)
 * @param context Cookie context (1, 3)
 *
 * @return IMappIntelligenceCookie
 */
const mappCookie: IMappIntelligenceCookie = mappIntelligence.getUserIdCookie(pixelVersion: string, context: string);

Example

const mappIntelligence = new MappIntelligenceTracking(mappConfig);
// before track(): the everID is added to the request
const mappUserCookie = mappIntelligence.getUserIdCookie(
    MappIntelligenceTracking.SMART,
    MappIntelligenceTracking.CLIENT_SIDE_COOKIE
);
try {
    await mappIntelligence.track(new MappIntelligenceDataMap().page(new MappIntelligencePage('en.home')));
} finally {
    await mappIntelligence.close();
}

if (mappUserCookie) {
    response.cookie(mappUserCookie.getName(), mappUserCookie.getValue(), {
        path: mappUserCookie.getPath(),
        secure: mappUserCookie.isSecure(),
        // seconds, Express expects milliseconds
        maxAge: mappUserCookie.getMaxAge() * 1000,
        httpOnly: mappUserCookie.isHttpOnly()
    });
}