Event Tracking

Use track(), on(), and once() to track custom events and listen for SDK events.

track()

on() / once()

Event Types

Tracking Events

Basic Usage

permutive.track('EventName', {
  property1: 'value',
  property2: 123
});

With Callback

permutive.track('Purchase', {
  product_id: 'SKU123',
  price: 29.99
}, {
  success: function(event) {
    console.log('Event tracked:', event);
  },
  error: function(errorType, errorMsg) {
    console.error('Tracking failed:', errorType, errorMsg);
  }
});

With Beacon API

Force use of the Beacon API for reliable tracking during page unload:

permutive.track('PageExit', {
  time_on_page: 120
}, {
  useBeacon: true
});

track() Method

Signature

permutive.track(eventName, properties, options)

Parameters

Parameter	Type	Required	Description
`eventName`	string	Yes	Name of the event
`properties`	object	No	Event properties
`options`	object	No	Tracking options

Options

Option	Type	Description
`success`	function	Called when event is accepted
`error`	function	Called on tracking error
`useBeacon`	boolean	Force Beacon API usage

Return Value

Returns a Promise that resolves with the event object:

permutive.track('MyEvent', { data: 'value' })
  .then(function(event) {
    console.log('Tracked:', event);
  })
  .catch(function(error) {
    console.error('Error:', error);
  });

Event Examples

E-commerce
User Actions
Engagement
Subscription

// Product view
permutive.track('ProductView', {
  product_id: 'SKU123',
  product_name: 'Blue Widget',
  category: 'Widgets',
  price: 29.99,
  currency: 'USD'
});

// Add to cart
permutive.track('AddToCart', {
  product_id: 'SKU123',
  quantity: 2,
  cart_value: 59.98
});

// Purchase
permutive.track('Purchase', {
  order_id: 'ORDER-456',
  products: [
    { id: 'SKU123', quantity: 2 }
  ],
  total: 59.98,
  currency: 'USD',
  payment_method: 'credit_card'
});

// Login
permutive.track('Login', {
  method: 'email',
  is_new_session: true
});

// Registration
permutive.track('Registration', {
  signup_source: 'homepage_banner',
  plan_type: 'premium'
});

// Search
permutive.track('Search', {
  query: 'blue widgets',
  results_count: 42
});

// Share
permutive.track('Share', {
  content_type: 'article',
  content_id: 'article-123',
  platform: 'twitter'
});

// Button click
permutive.track('ButtonClick', {
  button_id: 'cta-signup',
  button_text: 'Start Free Trial',
  page_section: 'hero'
});

// Tab switch
permutive.track('TabSwitch', {
  from_tab: 'overview',
  to_tab: 'pricing'
});

// Modal view
permutive.track('ModalView', {
  modal_name: 'newsletter-popup',
  trigger: 'exit_intent'
});

// Subscription start
permutive.track('SubscriptionStart', {
  plan_id: 'premium-monthly',
  plan_name: 'Premium',
  price: 9.99,
  billing_period: 'monthly'
});

// Paywall hit
permutive.track('PaywallHit', {
  paywall_type: 'hard',
  article_id: 'article-123',
  articles_read: 5
});

// Trial started
permutive.track('TrialStarted', {
  trial_length_days: 14,
  plan_type: 'premium'
});

Event Listeners

on() - Persistent Listener

Listen for all occurrences of an event:

// Listen for all Pageview events
permutive.on('Pageview', function(event, error) {
  if (error) {
    console.error('Event error:', error);
    return;
  }
  console.log('Pageview tracked:', event);
});

// Listen for custom events
permutive.on('Purchase', function(event) {
  analytics.trackRevenue(event.properties.total);
});

once() - Single Listener

Listen for only the first occurrence:

// Listen for first Pageview only
permutive.once('Pageview', function(event) {
  console.log('First pageview:', event);
});

// Wait for SDK ready event
permutive.once('permutive:ready', function() {
  console.log('SDK is ready');
});

Pattern Matching

Use regex to match multiple event types:

// Listen for all events starting with "Video"
permutive.on(/^Video/, function(event) {
  console.log('Video event:', event.name, event);
});

// Listen for all Purchase-related events
permutive.on(/Purchase|AddToCart|Checkout/, function(event) {
  console.log('E-commerce event:', event.name);
});

Removing Listeners

Store the listener reference to remove later:

var listener = permutive.on('Pageview', function(event) {
  console.log('Pageview:', event);
});

// Later, remove the listener
listener.remove();

Standard Event Types

The SDK defines these standard event types:

Event	Description
`Pageview`	Page load (via web addon)
`PageviewEngagement`	User engagement signals
`PageviewComplete`	User leaves page
`FormSubmission`	Form submitted
`LinkClick`	Link clicked
`Videoview`	Video playback started
`VideoEngagement`	Video engagement signals
`VideoCompletion`	Video completed
`SegmentEntry`	User entered a cohort
`SegmentExit`	User exited a cohort

Standard events (Pageview, etc.) are tracked automatically by the web addon. Use track() for custom events.

SDK Events

Listen for internal SDK events:

// SDK ready
permutive.on('permutive:ready', function() {
  console.log('SDK initialized');
});

// Realtime data ready
permutive.on('permutive:realtime', function() {
  console.log('Realtime cohort data available');
});

// SDK reset
permutive.on('permutive:reset', function() {
  console.log('SDK state was reset');
});

// Web addon ready
permutive.on('permutive:web:ready', function() {
  console.log('Web addon initialized');
});

Best Practices

Use Descriptive Event Names

// Good - clear, specific names
permutive.track('ArticleRead', {...});
permutive.track('NewsletterSignup', {...});
permutive.track('PremiumTrialStarted', {...});

// Avoid - vague or generic names
permutive.track('Click', {...});
permutive.track('Event', {...});
permutive.track('Action', {...});

Include Relevant Properties

// Good - actionable properties
permutive.track('Purchase', {
  order_id: 'ORDER-123',
  total: 99.99,
  currency: 'USD',
  product_count: 3,
  coupon_used: true
});

// Avoid - too few or irrelevant properties
permutive.track('Purchase', {
  timestamp: Date.now()  // Already captured automatically
});

Track at the Right Time

// Good - track when action completes
function onPurchaseComplete(order) {
  permutive.track('Purchase', {
    order_id: order.id,
    total: order.total
  });
}

// Avoid - tracking before action completes
function onCheckoutClick() {
  permutive.track('Purchase', {...});  // Purchase hasn't happened yet!
  processPayment();
}

Don't Over-Track

Track meaningful user actions, not every interaction:

// Good - meaningful actions
permutive.track('AddToCart', {...});
permutive.track('Search', {...});

// Avoid - excessive tracking
permutive.track('MouseMove', {...});
permutive.track('Scroll', {...});
permutive.track('Focus', {...});

Handle Errors

permutive.track('ImportantEvent', properties, {
  success: function(event) {
    // Event tracked successfully
  },
  error: function(type, msg) {
    // Log or handle error
    errorLogger.log('Permutive tracking failed', type, msg);
  }
});

Tracking on Page Unload

For events that must be tracked when the user leaves:

// Use Beacon API for reliable delivery
window.addEventListener('beforeunload', function() {
  permutive.track('PageExit', {
    time_on_page: calculateTimeOnPage()
  }, {
    useBeacon: true
  });
});

The web addon automatically tracks PageviewComplete on page unload, so you don’t need to track basic exit events manually.

Debugging

Enable debug mode to see all tracked events:

?permutive_debug=true

Console output:

[Permutive] Tracking: Purchase {order_id: "123", total: 99.99}
[Permutive] Event accepted: 1/1

Troubleshooting

Events not appearing in dashboard

Problem: track() called but no events in dashboard.Solutions:

Check consent is granted (if consentRequired: true)
Verify SDK is initialized
Enable debug mode to see if events are accepted
Check for JavaScript errors before track call
Allow processing time (events may take minutes to appear)

Callback not firing

Problem: Success/error callbacks not called.Solutions:

Verify callback functions are defined correctly
Check for errors in callback code
Ensure SDK is loaded before tracking

Properties missing from event

Problem: Event tracked but some properties missing.Solutions:

Check property names match expected schema
Verify property types are correct
Look for undefined values being passed
Check for typos in property names

Event Properties

Structure event data

Pageview Tracking

Automatic pageview tracking

Cohorts

Events power cohort membership

Connectivity Events

Event schema documentation

Get Started

Products

SDKs

Governance

track()

on() / once()

Event Types

Tracking Events

Basic Usage

With Callback

With Beacon API

track() Method

Signature

Parameters

Options

Return Value

Event Examples

Event Listeners

on() - Persistent Listener

once() - Single Listener

Pattern Matching

Removing Listeners

Standard Event Types

SDK Events

Best Practices

Tracking on Page Unload

Debugging

Troubleshooting

Event Properties

Pageview Tracking

Cohorts

Connectivity Events

Get Started

Products

SDKs

Governance

track()

on() / once()

Event Types

​Tracking Events

​Basic Usage

​With Callback

​With Beacon API

​track() Method

​Signature

​Parameters

​Options

​Return Value

​Event Examples

​Event Listeners

​on() - Persistent Listener

​once() - Single Listener

​Pattern Matching

​Removing Listeners

​Standard Event Types

​SDK Events

​Best Practices

​Tracking on Page Unload

​Debugging

​Troubleshooting

​Related Documentation

Event Properties

Pageview Tracking

Cohorts

Connectivity Events

Tracking Events

Basic Usage

With Callback

With Beacon API

track() Method

Signature

Parameters

Options

Return Value

Event Examples

Event Listeners

on() - Persistent Listener

once() - Single Listener

Pattern Matching

Removing Listeners

Standard Event Types

SDK Events

Best Practices

Tracking on Page Unload

Debugging

Troubleshooting

Related Documentation