Dev Docs

Appearance

User ID ​

Learn how to pass a custom user identifier to improve cross-session tracking accuracy.

Overview ​

A user identifier helps marketing platforms to stitch together a unique user's journey across multiple sessions and prevents inflated user counts.

Elevar's auto-generated user ID relies on browser storage, which can have a lifetime of just 7 days depending on browser settings. This short lifetime can cause:

  • User count inflation: One user appears as multiple users in GA4 after 7 days
  • Broken journey tracking: User sessions don't connect across longer time periods
  • Session enrichment gaps: Elevar can't recognize returning users and enrich data with full user identifiers

Passing your own user ID helps avoid these issues. To do this, you must either:

  • Retrieve a user ID from a server-set cookie that you configure manually
  • Use fingerprinting software to generate a long lasting user ID that you trust

TIP

Implementing a custom user ID is a best practice for all implementations to ensure accurate user tracking and optimal performance of Elevar's Session Enrichment feature.

How to Pass Your Own User ID ​

Pass User ID: ​

You can provide your own user ID by defining a global function before the Elevar snippet runs. This code must execute before the Elevar snippet that you copied from the Elevar app. If the Elevar script runs first, your custom user ID will not be recognized.

javascript
const getMyUserId = async () => Promise.resolve("my_custom_user_id");

window.ElevarUserIdFn = async () => {
  const userId = await getMyUserId();
  return userId;
};

WARNING

If you run the Elevar script first, your custom user ID will not be recognized. The function must be defined on ever page, this doesn't include virtual page changes. The window.ElevarUserIdFn must return a string or a promise to a string.

Verify the User ID: ​

Once implemented, any Data Layer event will include your custom user ID. You can verify this by inspecting the most recent Elevar Data Layer event:

javascript
console.log(window.ElevarDataLayer.at(-1)?.marketing?.user_id);

Implementation Examples ​

Defining the User ID Function in Next.js: ​

If you have used the following to load the Elevar snippet using Next.js application or inline scripts, define window window.ElevarUserIdFn at the top of the same script that loads the Elevar snippet.

If you have added our snippet via a useEffect at the top level of your app (ensuring that it only fires once per hard page load), you can either define window.ElevarUserIdFn at the top of that effect, or outside of the component that calls that effect (but in the same file).

Server Setting the User ID From Next.js: ​

Server setting the user ID from Next.js can be achieved with the proxy.js|ts file. Follow this guide to learn more.

javascript
import { NextResponse } from "next/server";

// Can be whatever you want
const cookieName = "custom_user_id";

export function middleware(request) {
  const cookie = request.headers.get(cookieName);
  const response = NextResponse.next();

  if (!cookie) {
    const cookieValue = crypto.randomUUID();
    response.headers.set("Set-Cookie", `${cookieName}=${cookieValue}`);
  }

  return response;
}

Shopify Hydrogen Implementation ​

Only for Shopify Headless integrations

For Hydrogen headless customers, you can retrieve the Client ID provided by Shopify using getClientBrowserParameters():

javascript
import { getClientBrowserParameters } from "@shopify/hydrogen";

window.ElevarUserId = () => getClientBrowserParameters().uniqueToken;

Important Notes ​

  • Testing requires clean state: If you've run the Elevar script before defining your user ID function, clear all cookies and local storage to test properly.
  • No impact on existing users: For customers already using Elevar's standard user IDs, implementing a custom user ID won't cause an increase in new user traffic. If a user's previous ID exists in local storage or cookies, Elevar will continue using it.

Copyright © 2025 Elevar