​
Data types

The core type for identifying a user in your application.

interface EndUserData {
  /**
   * Required unique identifier for the user.
   * Use a stable, persistent ID from your authentication system.
   */
  userId: string;
  
  /**
   * Optional full name of the user.
   */
  name?: string;
  
  /**
   * Optional email address of the user.
   */
  email?: string;
  
  /**
   * Optional URL to the user's avatar image.
   */
  avatarUrl?: string;
  
  /**
   * Optional HMAC signature for verifying user identity.
   * This should be generated server-side using your Pointer secret key.
   */
  hmacSignature?: string;
  
  /**
   * Optional custom data for storing additional user information.
   * This can include any JSON-serializable data.
   */
  customData?: Record<string, any>;
}

​
React hook API

​
useUser

function useUser(): {
  /**
   * The current user data, or undefined if no user is set.
   */
  userData: EndUserData | undefined;
  
  /**
   * Set or update the user data.
   * This will replace any existing user data.
   */
  setUserData: (userData: EndUserData) => void;
  
  /**
   * Clear all user data.
   * This is typically used during logout.
   */
  clearUserData: () => void;
  
  /**
   * Track a custom event.
   */
  trackEvent: (event: UserEvent) => Promise<void>;
  
  /**
   * Update the overall onboarding status for the user.
   */
  updateOnboardingStatus: (completed: boolean) => Promise<void>;
  
  /**
   * Update progress for a specific onboarding step.
   */
  updateOnboardingProgress: (progress: OnboardingProgress) => Promise<void>;
}

​
Direct API methods

For use outside of React components or for non-React applications.

​
Props API

interface PointerProviderProps {
  /**
   * Your Pointer API key from the dashboard.
   */
  apiKey: string;
  
  /**
   * Optional user data to identify the current user.
   */
  userData?: EndUserData;
  
  /**
   * Optional first name of the user (legacy).
   * For new applications, use userData.name instead.
   * @deprecated
   */
  userFirstName?: string;
  
  // ... other props
}

​
Flow completion behavior

When a user completes all steps in a flow, this completion is registered in their user data. Once a flow is registered as complete, it cannot be started again for that user, enabling one-time onboarding experiences.

​
Error handling

try {
  await trackEvent({
    eventType: 'FEATURE_USAGE',
    eventName: 'export_report'
  });
  console.log('Event tracked successfully');
} catch (error) {
  console.error('Failed to track event:', error);
  // Handle error (retries, fallbacks, etc.)
}

Most user tracking operations are designed to fail gracefully to prevent disrupting the user experience. Errors are logged but don’t typically cause application failures.

​
Data persistence

User data is persisted in the following ways:

  • In-memory cache: For fast access during the current session
  • Local storage: For persistence across page reloads
  • Server: For analytics and personalization

​
Security considerations

  • Sensitive data is never stored in customData field
  • User data is only accessible within your application domain