Advanced

Custom Events

Track user interactions beyond pageviews — signups, purchases, clicks, and more.

Basic Usage

Use phi.track() to send custom events:

JavaScript

// Track a simple event
phi.track('ButtonClicked');

// Track with metadata
phi.track('SignupCompleted', {
  plan: 'premium',
  source: 'landing-page'
});

Common Patterns

User Signup

Track when users complete registration.

phi.track('Signup', {
  method: 'email',
  plan: 'free'
});

Add to Cart

Track ecommerce cart additions.

phi.track('AddToCart', {
  productId: 'SKU-123',
  price: 49.99
});

Purchase

Track successful transactions.

phi.track('Purchase', {
  orderId: 'ORD-456',
  value: 99.99,
  currency: 'USD'
});

CTA Click

Track important button clicks.

phi.track('CTAClicked', {
  button: 'hero-signup',
  page: '/landing'
});

HTML Integration

Track events directly from HTML elements:

HTML

<!-- Track button click -->
<button onclick="phi.track('DownloadClicked', { file: 'whitepaper.pdf' })">
  Download Whitepaper
</button>

<!-- Track form submission -->
<form onsubmit="phi.track('ContactFormSubmit'); return true;">
  ...
</form>

<!-- Track link click -->
<a href="/pricing" onclick="phi.track('PricingViewed')">
  View Pricing
</a>

React Example

TSX

function SignupButton() {
  const handleClick = () => {
    // Track the click
    window.phi?.track('SignupStarted', { 
      source: 'header' 
    });
    
    // Navigate to signup
    router.push('/signup');
  };

  return (
    <button onClick={handleClick}>
      Get Started
    </button>
  );
}

Naming Conventions

✓Use PascalCase for event names: UserSignup
✓Use camelCase for metadata keys: productId
✓Be specific: CheckoutCompleted not checkout
✗Avoid special characters in event names

Limits & Best Practices

•Metadata size: Keep under 2KB per event
•Event name length: Max 64 characters
•Focus on conversions: Track meaningful actions, not every click
•Consistent naming: Use the same event name across your app