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.

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