User Identification

Connect anonymous visitors to known user profiles for enhanced analytics.

User Identification

EngageTrack tracks visitors anonymously by default. The Identify API lets you connect an anonymous visitor to a known user profile after they log in or sign up, enriching your analytics with user-level data.

The Identify API

window.engagetrack.identify(userId, {
	name: "Jane Smith",
	email: "[email protected]",
	avatar: "https://example.com/avatars/jane.jpg",
	custom: {
		plan: "pro",
		company: "Acme Inc",
	},
});

Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	A unique, stable identifier for the user (e.g., database ID, auth provider ID).
`traits.name`	string	No	Display name.
`traits.email`	string	No	Email address. Used for email-based revenue attribution.
`traits.avatar`	string	No	URL to the user's avatar image. Displayed in the visitor timeline.
`traits.custom`	object	No	Key-value pairs of custom properties (e.g., plan, company, role).

When to Call Identify

Call identify() after the user's identity is confirmed — typically right after login or signup:

// After successful login
async function onLogin(credentials) {
	const user = await api.login(credentials);
 
	// Identify the visitor with EngageTrack
	window.engagetrack.identify(user.id, {
		name: user.name,
		email: user.email,
	});
}

// After successful signup
async function onSignup(formData) {
	const user = await api.register(formData);
 
	window.engagetrack.identify(user.id, {
		name: user.name,
		email: user.email,
		custom: {
			signup_source: "landing-page",
		},
	});
}

You only need to call identify() once per session. The SDK links the current anonymous visitor ID to the user profile on the server.

React / Next.js Example

"use client";
 
import { useEffect } from "react";
import { useAuth } from "@/hooks/useAuth";
 
export function IdentifyUser() {
	const { user } = useAuth();
 
	useEffect(() => {
		if (user && typeof window !== "undefined" && window.engagetrack) {
			window.engagetrack.identify(user.id, {
				name: user.name,
				email: user.email,
				avatar: user.avatar,
			});
		}
	}, [user]);
 
	return null;
}

Place this component inside your authenticated layout so it runs whenever a logged-in user loads the page.

How It Works

When you call identify(), the SDK sends a POST request to the /api/v1/identify endpoint with:

The current anonymous visitor_uid (from localStorage — requires storage mode)
The user_id you provided
Any traits (name, email, avatar, custom)

The server links the anonymous visitor record to the user profile. All past and future events for that visitor are associated with the identified user.

identify() requires storage mode (data-persistence="storage") because it needs a persistent visitor ID to link across sessions. In the default memory mode, calling identify() will log a warning and return without effect.

Visitor Timeline Enrichment

Once a visitor is identified, their profile in the Visitors dashboard shows:

Name and avatar instead of an anonymous ID
Email address for quick reference
Custom properties as metadata tags
Full event timeline including pre-identification pageviews

Revenue Attribution

Identified users unlock email-based revenue attribution. When a payment webhook arrives with an email address, EngageTrack can match it to an identified visitor — even if the engagetrack_visitor_id metadata was not included in the payment.

See Revenue Attribution for the full attribution priority chain.