Utils
    • 7 Minutes to read
    • Dark
      Light

    Utils

    • Dark
      Light

    Article summary

    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');


    Was this article helpful?

    ESC

    AI Assistant, facilitating knowledge discovery through conversational intelligence