Skip to main content

User Identification

Identifying users allows you to associate sessions with specific people in your application. This makes it easier to find sessions, understand user journeys, and provide better support.

Why Identify Users?​

Without user identification, sessions appear as anonymous visitors. By identifying users, you can:

  • Search for specific users in the Sessions list
  • See user details like email and name alongside sessions
  • Track user journeys across multiple sessions
  • Provide better support by quickly finding a user's sessions

Identifying Users​

Use window.recapt('identify', {...}) after a user logs in or when you know who they are:

window.recapt("identify", {
  uid: "USER_ID", // Required: Your user's unique identifier
  email: "user@email.com", // Optional: User's email
  nickname: "johndoe", // Optional: User's display name/username
});

User Properties​

PropertyRequiredDescription
uidYesA unique identifier for the user. This should be consistent across sessions (e.g., database ID, Auth0 ID).
emailNoThe user's email address. Highly recommended for searchability.
nicknameNoThe user's username or display name.
tip

The uid should be a stable identifier that doesn't change. Database IDs or authentication provider IDs work best. Avoid using email addresses as the uid since users might change their email.

When to Identify Users​

Call recapt('identify', {...}) in these scenarios:

After Login​

// Example: After successful authentication
async function handleLogin(email, password) {
  const user = await authenticateUser(email, password);

  // Identify the user in Recapt
  window.recapt("identify", {
    uid: user.id,
    email: user.email,
    nickname: user.nickname,
  });

  // Continue with your app logic
  redirectToDashboard();
}

After Signup​

// Example: After user registration
async function handleSignup(userData) {
  const newUser = await createUser(userData);

  // Identify the new user
  window.recapt("identify", {
    uid: newUser.id,
    email: newUser.email,
    nickname: newUser.nickname,
  });

  // Continue with onboarding
  startOnboarding();
}

On Page Load (for logged-in users)​

// Example: Check for existing session on app load
function initializeApp() {
  const currentUser = getCurrentUser(); // Your auth logic

  if (currentUser) {
    window.recapt("identify", {
      uid: currentUser.id,
      email: currentUser.email,
      nickname: currentUser.nickname,
    });
  }
}

Clearing User Identification (Logout)​

When a user logs out, clear their identification:

window.recapt("identify", {
  uid: undefined,
  email: undefined,
  nickname: undefined,
});

React / Next.js Example​

For React and Next.js applications, we recommend using a setup component that handles script loading and user identification together. This works with the dynamic script loading approach described in the Installation guide.

Complete Setup Component​

"use client";

import { useEffect, useRef, useState } from "react";
import { useAuth } from "./your-auth-provider";

declare global {
  interface Window {
    Recapt: any;
    recapt: (action: string, data: any) => void;
  }
}

export default function RecaptSetup() {
  const { user, isLoading } = useAuth();
  const [isScriptLoaded, setIsScriptLoaded] = useState(false);
  const retryCount = useRef(0);
  const maxRetries = 50;

  // Load the Recapt script once
  useEffect(() => {
    if (typeof window === "undefined") return;

    const script = document.createElement("script");
    script.src = "https://cdn.recapt.app/browser/glimt.js";
    script.async = true;
    script.setAttribute("data-public-key", "YOUR_API_KEY");
    script.setAttribute("data-persist", "");

    script.onload = () => setIsScriptLoaded(true);
    document.body.appendChild(script);

    return () => {
      try {
        document.body.removeChild(script);
      } catch {}
    };
  }, []);

  // Identify user when auth state changes
  useEffect(() => {
    if (!isScriptLoaded || isLoading) return;

    const waitForRecapt = () => {
      if (!window.Recapt) {
        if (retryCount.current < maxRetries) {
          retryCount.current++;
          setTimeout(waitForRecapt, 100);
        }
        return;
      }

      retryCount.current = 0;

      // Identify or clear user
      window.recapt("identify", {
        uid: user?.id,
        email: user?.email,
        nickname: user?.nickname,
      });
    };

    waitForRecapt();
  }, [user, isLoading, isScriptLoaded]);

  return null;
}

Include this component in your app's root layout to ensure Recapt is set up on every page.

Best Practices​

  1. Identify early: Call recapt('identify', {...}) as soon as you know who the user is
  2. Use stable IDs: The uid should never change for a given user
  3. Include email: Even though optional, email makes searching much easier
  4. Don't over-identify: Only call identify once per session (or when user data changes)
  5. Handle logged-out users: Clear identification when users log out
  6. Wait for Recapt: In SPAs, ensure window.Recapt is available before calling methods

Privacy Considerations​

  • User identification data is associated with session recordings
  • Consider your privacy policy and GDPR compliance
  • You can use internal IDs instead of personal information if preferred
  • Email addresses in recordings are automatically obfuscated by default

Next Steps​