Skip to main content

Using a UUID to track site visitors

Abstract

Describes why tracking site visitors through a uuid is important and provides a code sample of how to do this.

When you call a Sitecore Search API, we recommend you create and send a universal unique identifier (uuid) for each site visitor. The uuid is a unique user ID that does not contain personally identifiable information (PII) like email or membership ID. Sitecore Search uses the uuid to tie a request to a visitor, which allows us to serve personalized search results and generate accurate analytics.

You must follow these rules when you generate a uuid:

  • The uuid must contain your domain ID. You can see your domain ID on the Customer Engagement Console (CEC) in the Developer Resources, API Access section.

  • The uuid must be in the <<your-domain-ID>>-xx-xx-4x-1p-<<xxxxx>> format where x is a random number.

Here is a sample uuid: 159871551-1g-i4-4x-1p-f5tdhddqwvywv7b9g2vy-1664852644904

One way to create and send a uuid is to set a cookie on the visitor's browser, generate a uuid, and persist the uuid in the cookie. The following code sample shows you how to do this:

/**
 * @description: Sets a cookie on the browser. Refer to https://www.w3schools.com/js/js_cookies.asp
 * @param {string} cname: Cookie name
 * @param {string} cvalue: Cookie value
 * @param {number} exdays: Expiry date in days
 */
function setCookie(cname, cvalue, exdays) {
    const d = new Date();
    d.setTime(d.getTime() + (exdays*24*60*60*1000));
    let expires = "expires="+ d.toUTCString();
    document.cookie = cname + "=" + cvalue + ";" + expires + ";path=/";
}
/**
 * @description: Gets a cookie already in browser. Returns empty if not exists.
 * Refer to https://www.w3schools.com/js/js_cookies.asp
 * @param cname
 * @returns {string}
 */
function getCookie(cname) {
    let name = cname + "=";
    let decodedCookie = decodeURIComponent(document.cookie);
    let ca = decodedCookie.split(';');
    for(let i = 0; i <ca.length; i++) {
        let c = ca[i
        ];
        while (c.charAt(0) === ' ') {
            c = c.substring(1);
        }
        if (c.indexOf(name) === 0) {
            return c.substring(name.length, c.length);
        }
    }
    return undefined;
}
/**
 * @description: Converts a digit to the string that belongs to.  
 * @param {number} i: Number to convert
 * @returns {string}
 */
function digit2string(i) {
    // 0-9 -> 0-9; 10-35 > a-z; 36-61 -> A-Z
    return String.fromCharCode(i < 10 ? i + 48 : i < 36 ? i + 87 : i + 29);
}


const getDomainId = () => {
    let uuid = getCookie('uuid');
    if (uuid) {
        return uuid;
    }
    const uuidx = 'xx-xx-4x-1p-'; // pattern of prefix to user id
    uuid = uuidx.replace(/[x
    ]/g, () => digit2string((Math.random() * 36) | 0));
    for (let i = 0; i < 5; i++) {
        uuid += ('0000' + ((Math.random() * 1679615) | 0).toString(36)).slice(-4);
    }
    let value = '<Fill this with domain id provided by Sitecore Search>';
    value += '-' + uid + '-' + Date.now();

    // Persisting the UUID
    setCookie('uuid', value,
    1);

    return value;
};