User Identification

User identification connects feedback and votes to specific users in your system. When you identify a user, their data is persisted in localStorage for subsequent sessions.

identify(user)

Associates the current session with a user.

async identify(user: UserIdentity): Promise<IdentifiedUser>

Parameters

interface UserIdentity {
  /** Your system's unique user ID (required) */
  externalId: string;
  /** User's email address */
  email?: string;
  /** User's display name */
  name?: string;
  /** URL to user's avatar image */
  avatarUrl?: string;
  /** Additional metadata to associate with the user */
  metadata?: Record<string, unknown>;
}

Returns

interface IdentifiedUser {
  id: string;
  email: string | null;
  name: string | null;
  avatarUrl: string | null;
  createdAt: string;
}

Example

import Feedhog from '@feedhog/js';

const feedhog = new Feedhog({ apiKey: 'fhpk_your_public_key' });

const user = await feedhog.identify({
  externalId: 'user-123',
  email: 'john@example.com',
  name: 'John Doe',
  avatarUrl: 'https://example.com/avatars/john.jpg',
  metadata: {
    plan: 'pro',
    company: 'Acme Inc',
    signupDate: '2024-01-15'
  }
});

console.log('User identified:', user.id);
console.log('Created at:', user.createdAt);

When to Call

Call identify() whenever a user logs in or when user data changes:

// After login
async function handleLogin(userData) {
  await feedhog.identify({
    externalId: userData.id,
    email: userData.email,
    name: userData.displayName
  });
}

// When user updates their profile
async function handleProfileUpdate(newProfile) {
  await feedhog.identify({
    externalId: currentUser.id,
    email: newProfile.email,
    name: newProfile.name,
    avatarUrl: newProfile.avatar
  });
}

user Property

Access the currently identified user:

const feedhog = new Feedhog({ apiKey: 'fhpk_your_public_key' });

// Check if user is identified
if (feedhog.user) {
  console.log('Current user:', feedhog.user.externalId);
  console.log('Email:', feedhog.user.email);
  console.log('Is identified:', feedhog.user.identified);
} else {
  console.log('No user identified');
}

CurrentUser Type

interface CurrentUser extends UserIdentity {
  /** Whether the user has been verified with the server */
  identified: boolean;
}

reset()

Clears the current user and removes stored data. Call this when a user logs out:

reset(): void

Example

// When user logs out
function handleLogout() {
  feedhog.reset();
  console.log('User data cleared');
  console.log('Current user:', feedhog.user); // null
}

Session Persistence

User data is automatically persisted in localStorage:

// First session
const feedhog = new Feedhog({ apiKey: 'fhpk_your_public_key' });
await feedhog.identify({
  externalId: 'user-123',
  email: 'john@example.com'
});

// Later session (same browser)
const feedhog2 = new Feedhog({ apiKey: 'fhpk_your_public_key' });
console.log(feedhog2.user); // User data restored from localStorage
// { externalId: 'user-123', email: 'john@example.com', identified: false }

The identified: false indicates the user data was restored from storage but not yet verified with the server. Call identify() again to verify and update the user data.

Anonymous Feedback

You can submit feedback without identifying a user:

const feedhog = new Feedhog({ apiKey: 'fhpk_your_public_key' });

// No identify() call - feedback is anonymous
const feedback = await feedhog.submit({
  title: 'Anonymous suggestion',
  type: 'idea'
});

Anonymous feedback:

Has no associated user in the dashboard
Cannot be tracked or attributed
Votes are tracked by IP address

React/Next.js Integration

'use client';

import { useEffect } from 'react';
import Feedhog from '@feedhog/js';
import { useAuth } from '@/hooks/use-auth';

const feedhog = new Feedhog({
  apiKey: process.env.NEXT_PUBLIC_FEEDHOG_API_KEY!
});

export function FeedhogIdentifier() {
  const { user, isAuthenticated } = useAuth();

  useEffect(() => {
    if (isAuthenticated && user) {
      feedhog.identify({
        externalId: user.id,
        email: user.email,
        name: user.name,
        avatarUrl: user.image
      }).catch(console.error);
    } else {
      feedhog.reset();
    }
  }, [isAuthenticated, user]);

  return null;
}

Best Practices

Identify early - Call identify() as soon as you have user data
Include email - Email helps with support and notification features
Use stable IDs - Use your database user ID as externalId
Update on changes - Re-identify when user profile data changes
Reset on logout - Always call reset() when users log out