- 7 Minutes to read
- Print
- DarkLight
Utils
- 7 Minutes to read
- Print
- DarkLight
This page provides a collection of utility methods that enhance the Smart Pixel's functionality by offering various tools for browser detection, cookie management, encoding, event handling, and more. These methods allow developers to easily perform common tasks.
Page request status
This method lets you check if a page request has already been sent. This can be useful for custom plugins that rely on a page request.
/**
* @returns {boolean}
*/
wtSmart.hasPageAlreadySent()
Browser
These methods allow you to check if the user is using a specific browser. Each method returns a boolean value (true or false) based on the user’s browser type. This can be useful when applying browser-specific fixes or optimizations in your application.
isOpera
Checks if the browser is Opera.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isOpera();
isIE
Checks if the browser is Internet Explorer.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isIE();
isMSIE
Detects the older MSIE version of Internet Explorer.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isMSIE();
isTrident
Checks if the Trident rendering engine is used (common in older versions of Internet Explorer).
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isTrident();
isEdge
Detects if the browser is Microsoft Edge.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isEdge();
isFirefox
Checks if the browser is Mozilla Firefox.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isFirefox();
isSafari
Detects if the browser is Apple Safari.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isSafari();
isChrome
Detects if the browser is Google Chrome.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isChrome();
isPhantom
Checks if the PhantomJS headless browser is being used.
/**
* @returns {boolean}
*/
wtSmart.utils.browser.isPhantom();
Cookie
With the “cookie” method, you can set and retrieve cookie values. This method supports options such as setting the cookie’s duration, path, domain, and security level. Cookies can be used to store session data, user preferences, or tracking information.
Example use cases:
Set a session cookie to track user activity during a browsing session.
Retrieve the value of an existing cookie to persist user preferences across sessions.
/**
* @param {string} name
* @param {string} [value=""]
* @param {number} [duration=0]
* @param {string} [path="/"]
* @param {string} [domain="current domain without subdomain"]
* @param {boolean} [secure=false]
*
* @returns {string|boolean}
*/
wtSmart.utils.cookie(name, value, duration, path, domain, secure);
Example
// set session cookie
wtSmart.utils.cookie('session_cookie', '1');
// set cookie with 6 month duration
wtSmart.utils.cookie('ever_cookie', '1', 6*30*24*60);
wtSmart.utils.cookie('ever_cookie', '1', 6*30*24*60, '/path', 'sub.domain.tld', true);
// get cookie value
var cookieValue = wtSmart.utils.cookie('cookie_name');
Crypto
The “crypto” utility provides methods for encoding and decoding URL components, as well as hashing strings using SHA256 and MD5 algorithms. These methods are useful for secure data handling, such as creating unique identifiers or ensuring the integrity of transmitted data.
URL
With "URL" you have the option to "encode" and "decode" URI components.
encode
Encodes a URI component into a format suitable for use in URLs.
/**
* @param {string} str
*
* @returns {string}
*/
wtSmart.utils.crypto.URL.encode(str);
decode
Decodes an encoded URI component back to its original form.
/**
* @param {string} str
*
* @returns {string}
*/
wtSmart.utils.crypto.URL.decode(str);
Example
wtSmart.utils.crypto.URL.encode('äöü'); // %C3%A4%C3%B6%C3%BC
wtSmart.utils.crypto.URL.decode('%C3%A4%C3%B6%C3%BC'); // äöü
SHA256
encode
Hashes a string using the SHA256 algorithm, commonly used for secure data storage or transmission.
/**
* @param {string} str
*
* @returns {string}
*/
wtSmart.utils.crypto.SHA256.encode(str);
Example
wtSmart.utils.crypto.SHA256.encode('üöäÄÜÖ'); // c245f5277e70122d7e8427e6275cbd1a80f57cd7ec70a3e76f40d54a3687d02c
MD5
With "MD5" you have the option to "encode" strings to a MD5 hash.
encode
Hashes a string using the MD5 algorithm, another method for generating a fixed-length representation of a string.
/**
* @param {string} str
*
* @returns {string}
*/
wtSmart.utils.crypto.MD5.encode(str);
example
wtSmart.utils.crypto.MD5.encode('üöäÄÜÖ'); // 17cbf9298930599d4c7f06b9d46cb187
Event
The “event” utility provides methods to register and unregister event handlers for HTML elements. These are particularly useful when dynamically adding or removing event listeners in JavaScript-based applications.
register
Registers an event for an HTML element, such as a click event on a button or link.
/**
* @param {HTMLElement|Window|Document} obj
* @param {string} evt
* @param {function(evt)} callback
*/
wtSmart.utils.event.register(obj, evt, callback);
unregister
Removes the previously registered event from an HTML element.
/**
* @param {HTMLElement|Window|Document} str
* @param {string} evt
* @param {function(evt)} callback
*/
wtSmart.utils.event.unregister(obj, evt, callback);
Example
Dynamically add a click event listener to all links on a page, then remove it from a specific link when no longer needed.
var eventCallback = function(evt) {
// do something after click
};
// register a click event
for (var i = 0, l = document.links.length; i < l; i++) {
wtSmart.utils.event.register(document.links[i], "click", eventCallback);
}
// unregister a click event
wtSmart.utils.event.unregister(document.links[15], "click", eventCallback);
Identifier
The “identifier” methods provide ways to manage unique identifiers like the Mapp Ever ID. These methods allow developers to retrieve or set these IDs, as well as force a new session when required.
everId
Retrieves or sets the Mapp Intelligence Ever ID, a unique identifier used for tracking.
/**
* @param {string} [everId] - format (^\d{19}$)
*
* @returns {string}
*/
wtSmart.utils.identifier.everId(everId);
forceNewSession
Forces the creation of a new session, resetting session-based tracking.
/**
*
*/
wtSmart.utils.identifier.forceNewSession();
Example
// get existing Webtrekk Ever ID
var everId = wtSmart.utils.identifier.everId();
// set Webtrekk everId
wtSmart.utils.identifier.everId('0123456789012345678');
Image
The “image” method allows you to load an image asynchronously, with an optional callback function that triggers after the image is loaded or when a timeout is reached. This is useful for tracking purposes or for lazy-loading images.
/**
* @param {string} imageURL
* @param {function(HTMLImageElement, string, number)} [callback]
* @param {number=2000} [timeout]
*/
wtSmart.utils.image(imageURL, callback, timeout);
Example
Load a tracking pixel asynchronously and execute a callback function if the image is successfully loaded or if it times out.
/**
* @param {HTMLImageElement} img
* @param {string} status - (success, error, timeout)
* @param {number} executionTime
*/
var imageCallback = function(img, status, executionTime)) {
// do something
};
var imageURL = 'https://sub.domain.tld/track?page=start&t=' + (new Date().getTime());
// load an image asynchronous
wtSmart.utils.image(imageURL);
// load an image asynchronous with callback
wtSmart.utils.image(imageURL, imageCallback, 1000);
Include
The “include” method allows you to load JavaScript files asynchronously. You can define an optional callback function that triggers when the script has finished loading. This is useful for optimizing load times or ensuring certain scripts are loaded only when needed.
/**
* @param {string} scriptURL
* @param {function()} [callback]
*/
wtSmart.utils.include(scriptURL, callback);
/**
* @param {{
* src: string,
* [required=false]: boolean
* }[]} scriptURL
* @param {function()} [callback]
*/
wtSmart.utils.include(scriptURL, callback);
Example
Load multiple JavaScript files dynamically, ensuring that specific files are required for execution before others.
// load one js file
wtSmart.utils.include('/path/to/my/js/file.js', function() {
// do something and more
});
// load more js files
wtSmart.utils.include(
[
{src: '/path/to/my/js/file_1.js', required: true},
{src: 'sub.domain.tld/path/to/my/js/file_2.js'},
{src: '//sub.domain.tld/path/to/my/js/file_3.js', required: true}
],
function() {
// do something and more, if 'file_1' and 'file_3' was successfully loaded
}
);
OptOut
These methods allow you to manage opt-out cookies for tracking, giving users the ability to opt out of being tracked by setting first-party or third-party cookies.
getTrackingOptOut
Returns the current opt-out status.
/**
* @returns {boolean}
*/
wtSmart.utils.optout.getTrackingOptOut();
setTrackingOptOut
Sets the opt-out cookie, with options to customize the duration and execute a callback after setting.
/**
* @param {number} [duration=5*12*30*24*60]
* @param {function} [callback]
*/
wtSmart.utils.optout.setTrackingOptOut(duration, callback);
getAnonymousCookie
Retrieves the status of the anonymous tracking cookie based on the advanced configuration settings.
Depending on the settings in the advanced configuration, the value "true" of the cookie refers to different tracking scenarios:
When setting the user-identifiable cookie by default and providing the possibility to opt-out of user-identifiable tracking, "true" refers to anonymous tracking and no user-identifiable cookie is set.
When using anonymous tracking by default, "true" means that the user agreed to user-identifiable tracking and the respective cookie and information is set and tracked.
/**
* @returns {boolean}
*/
wtSmart.utils.optout.getAnonymousCookie();
setAnonymousCookie
Sets the anonymous tracking cookie, indicating whether the user is tracked anonymously or with a user-identifiable cookie.
/**
* @param {number} [duration=5*12*30*24*60]
*/
wtSmart.utils.optout.setAnonymousCookie(duration);
deleteAnonymousCookie
Deletes the anonymous tracking cookie, resetting any user-identifiable tracking settings.
wtSmart.utils.optout.deleteAnonymousCookie();
Example
// get the optout status
var optoutStatus = wtSmart.utils.optout.getTrackingOptOut();
// set the optout cookie with a default duration of 5 years
wtSmart.utils.optout.setTrackingOptOut();
// set the optout cookie with a duration of 6 months
wtSmart.utils.optout.setTrackingOptOut(6*30*24*60);
// set the optout cookie with a duration of 6 months an execute afterwards the callback method
wtSmart.utils.optout.setTrackingOptOut(6*30*24*60, function(img, status) {
var message = 'The optout cookie was set successfully.';
if (status !== 'success') {
message = 'An error has occurred, please try again later.';
}
alert(message);
});
// get the anonymous cookie status
var anonymous = wtSmart.utils.optout.getAnonymousCookie();
// set the anonymous cookie with the default duration of 5 years
wtSmart.utils.optout.setAnonymousCookie();
// set the anonymous cookie with a duration of 6 months
wtSmart.utils.optout.setAnonymousCookie(6*30*24*60);
// delete the anonymous cookie
wtSmart.utils.optout.deleteAnonymousCookie();
Parameter
The “parameter” method retrieves the value of a URL parameter. This is useful for tracking campaign data or customizing content based on URL parameters.
/**
* @param {string} param
* @param {string} [url=document.location.href]
* @param {*} [def=false]
*
* @returns {*}
*/
wtSmart.utils.parameter(param, url, def);
Example
Retrieve the wt_mc parameter from the URL to track marketing campaigns.
// get an url parameter value
var parameterValue = wtSmart.utils.parameter('wt_mc', document.location.href, false);
Referrer
The “referrer” method retrieves or sets the referrer URL, which is used as the origin referrer for the SmartPixel. This can be useful for tracking the source of incoming traffic.
/**
* @param {string} [referrer]
*
* @returns {string}
*/
wtSmart.utils.referrer(referrer);
Example
// get referrer url
var referrer = wtSmart.utils.referrer();
// set referrer url
wtSmart.utils.referrer('https://sub.domain.tld/path/to/page');
Url
The “url” method retrieves or sets the current page URL, allowing you to dynamically modify or track the URL used by the SmartPixel.
/**
* @param {string} [url]
*
* @returns {string}
*/
wtSmart.utils.url(url);
Example
// get page url
var pageURL = wtSmart.utils.url();
// set page url
wtSmart.utils.url('https://sub.domain.tld/path/to/my/current/page');