Using a UUID to track site visitors

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) such as an email address or membership ID. Sitecore Search uses the uuid to tie a request to a visitor across multiple sessions, which allows us to serve personalized search results and generate accurate analytics.

Sitecore Search requires that you create a seven-part UUID separated by hyphens, in this format:

<part1>-<part2>-<part3>-<part4>-<part5>-<part6>-<part7>

Here's what the different parts are:

<part1> is a constant, your domain ID. You can see your domain ID in Search in the domain name drop down list. For example, 159271561.
<part2> through <part5> is a four-part string. There are no length requirements. For simplicity and backward compatibility, we strongly recommend that you keep these constant across all visitors in your domain. Examples of this include y-d-7-n or a-b-c-d.
<part6> is a random alphanumeric string of at least 20 characters to uniquely identify the site visitor. For example, f5tdhddqwvywv7b9g2vy.
<part7> is the timestamp, in milliseconds, when the UUID was created. For example, 1664852644904.

Here's a sample uuid: 159271561-a-b-c-d-f5tdhddqwvywv7b9g2vy-1664852644904

Note

If your custom UUID does not follow the above format, ensure that your custom free-form ID is passed in context.user.user_id instead of context.user.uuid in your Search request.

For example, you want to create and persist a uuid in the following scenario:

You use cookies.
You want to store the UUID in a cookie.
You use your Search domain ID in the script to generate a UUID.

This sample code snippet shows how to generate a UUID:

const generateUUID = (domainId) => {
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 = domainId;
    value += '-' + uid + '-' + Date.now();
    return value;
}

const getDomainId = () => {
   let uuid = getCookie('uuid');
   if (uuid) {
        return uuid;
    }
    return generateUUID('<Fill this with your Search domain ID>')

}

This sample code snippet shows how to persist a UUID in a cookie:

/**
 * @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);
}

If you have suggestions for improving this article, let us know!