Identify logged-in users

Use Umami's Distinct ID and session data features to associate analytics with specific users across sessions and devices, while maintaining privacy.

When to use this#

• Track individual user journeys across multiple visits.
• Understand how specific users interact with your product.
• Connect events from different devices to the same person.
• Build user profiles based on behavior history.

Step 1: Assign a Distinct ID#

If the page knows the user when it loads (recommended)#

When your pages are rendered for a logged-in user, add the user's ID to the tracker script with the data-distinct-id attribute:

<script
  defer
  src="https://your-umami-instance/script.js"
  data-website-id="your-website-id"
  data-distinct-id="user-123"
></script>

The user is identified from the first pageview. This matters most for apps used inside companies: coworkers on the same office network often share an IP address and browser, and because Umami does not use cookies, it cannot tell them apart until they are identified. With data-distinct-id, there is no anonymous gap to mix up.

If the user logs in without a page reload#

In a single-page app, call umami.identify() with a unique identifier once the user logs in:

// After user logs in
umami.identify({ id: user.id });

Page views and events sent after this call are linked to the ID. The ones sent before it are anonymous. If your app reloads the page after login, prefer data-distinct-id.

The ID can be any string up to 50 characters: a user ID, email, or hash.

Step 2: Add session data (optional)#

You can attach additional properties to help identify and segment users:

umami.identify({
  id: user.id,
  name: user.name,
  plan: user.plan,
  company: user.company,
});

Session properties appear in the visitor profile and can be used for filtering.

Step 3: View user activity#

Navigate to Sessions in your Umami dashboard. Use the search bar to find a specific Distinct ID:

1. Enter the user's ID in the search field.
2. Umami shows all sessions associated with that ID across the selected time range.
3. Click on any session to see the full activity history: pages visited, events triggered, and timestamps. Since sessions linked to the same ID (e.g. from different devices) are combined automatically, this view shows the visitor's complete cross-device activity, not just the one session you clicked.

Framework examples#

Next.js (server-rendered)#

Render the tracker in your root layout and pass the logged-in user's ID:

import Script from 'next/script';
import { auth } from '@/auth';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth();

  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://your-umami-instance/script.js"
          data-website-id="your-website-id"
          data-distinct-id={session?.user?.id}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

The script loads once, so a client-side login that does not reload the page still needs umami.identify(), as in the examples below.

React (after login)#

function useIdentifyUser(user) {
  useEffect(() => {
    if (user) {
      umami.identify({ id: user.id, plan: user.plan });
    }
  }, [user]);
}

Next.js (App Router)#

'use client';
import { useSession } from 'next-auth/react';
import { useEffect } from 'react';

export function Analytics() {
  const { data: session } = useSession();

  useEffect(() => {
    if (session?.user) {
      umami.identify({ id: session.user.id });
    }
  }, [session]);

  return null;
}

Privacy considerations#

• Use internal user IDs rather than email addresses when possible.
• Umami stores session data server-side. No cookies are used.
• Users who are not logged in remain fully anonymous.
• You can use hashed identifiers (e.g., SHA-256 of the email) if you want to correlate data without storing PII.