How to Identify Users in Your App

Use the identify method to associate a unique identifier with each user. This enables accurate MAU tracking and personalized tour targeting.

Why identify users?

Without identification, Hopscotch uses browser cookies to track visitors. This has limitations:

• The same user on different devices counts as multiple users
• Clearing cookies creates a "new" user
• You can't target tours to specific users

By calling identify with a hop_visitor_lookup_id, you ensure each user is tracked accurately across devices and sessions.

Basic implementation

Call identify after the Hopscotch script loads and when you know who the user is (typically after login):

window.Hopscotch('identify', {
  hop_visitor_lookup_id: 'user_123',
});

The hop_visitor_lookup_id should be a unique, stable identifier for the user. Common choices:

• Email address: Easy to use, but changes if users update their email
• Internal user ID: Most reliable, doesn't change
• Database primary key: Guaranteed unique

When to call identify

Call identify as soon as you know who the user is:

• After login: When authentication completes
• On page load: If the user is already logged in
• After signup: When a new account is created

// Example: Call after your auth check
if (currentUser) {
  window.Hopscotch('identify', {
    hop_visitor_lookup_id: currentUser.email,
  });
}

React example

import { useEffect } from 'react';
import { useAuth } from './your-auth-hook';

function App() {
  const { user, isLoaded } = useAuth();

  useEffect(() => {
    if (!isLoaded || !user) return;

    window.Hopscotch('identify', {
      hop_visitor_lookup_id: user.email,
    });
  }, [isLoaded, user]);

  return <div>Your app</div>;
}

Adding custom properties

You can include additional properties alongside hop_visitor_lookup_id for tour targeting:

window.Hopscotch('identify', {
  hop_visitor_lookup_id: user.email,
  first_name: user.firstName,
  plan: user.subscription.plan,
  is_trial: user.subscription.isTrial,
  signup_date: user.createdAt.toISOString(),
});

These properties can be used to target tours to specific user segments. See Advanced Targeting with Custom Properties for details on using these for tour targeting.

Company identification

If your product has multi-user accounts (teams, organizations, companies), you can group users together by passing a company identifier. This enables company-level event targeting, where you can show content based on whether anyone in the company has performed certain actions.

window.Hopscotch('identify', {
  hop_visitor_lookup_id: user.email,
  hop_visitor_lookup_company_id: user.companyId,
  hop_visitor_company_name: user.companyName,
});

Why use company identification?

Company identification enables powerful targeting scenarios:

• Show onboarding to new team members when someone else in their company has already completed setup
• Skip setup tours if a teammate has already configured the feature
• Target expansion content to companies where no one has used a premium feature yet
• Coordinate messaging across team members based on collective behavior

Properties

Example with company data

window.Hopscotch('identify', {
  hop_visitor_lookup_id: currentUser.id,
  hop_visitor_lookup_company_id: currentUser.organization.id,
  hop_visitor_company_name: currentUser.organization.name,
  first_name: currentUser.firstName,
  role: currentUser.role,
});

Once you've set up company identification, you can use the "Company Event" filter in your targeting rules to target based on events from any user in the same company. See Custom Events for more details on company-level event targeting.

Handling user logout

When a user logs out, you don't need to do anything special. The next time identify is called with a different hop_visitor_lookup_id, Hopscotch automatically recognizes this as a new user and starts a fresh session.

Troubleshooting

Identify not working

Make sure the Hopscotch script has loaded before calling identify. If you're calling it immediately on page load, the script may not be ready yet.

// Wait for script to load
if (typeof window.Hopscotch === 'function') {
  window.Hopscotch('identify', { hop_visitor_lookup_id: user.id });
}

Related

• What is a Monthly Active User?
• Advanced Targeting with Custom Properties
• Browser SDK