Skip to main content
Events in Permutive consist of a name and properties object. Properties provide the context and data that powers cohort building and insights.

Property Types

Event Structure

Best Practices

​
Event Structure

Every event has a name and properties: 
permutive.track('EventName', {
  property1: 'value',
  property2: 123,
  nested: {
    property3: true
  }
});

​
Automatic Properties

The SDK automatically adds these properties to every event:
PropertyTypeDescription
timetimestampWhen the event occurred
session_idstringCurrent session identifier
view_idstringCurrent pageview identifier
client.urlstringCurrent page URL
client.referrerstringReferring URL
client.user_agentstringBrowser user agent
client.viewportobjectBrowser viewport dimensions
geo_infoobjectGeographic information (server-side)

​
Property Types

Permutive supports several property types: 
permutive.track('Article', {
  title: 'Breaking News',
  category: 'technology',
  author: 'Jane Smith'
});

​
Standard Events

The SDK defines standard event types with expected properties:

​
Pageview

Tracked automatically by the web addon: 
// Automatic via web addon
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Article Title',
      categories: ['news'],
      authors: ['Author Name'],
      publishedAt: '2024-01-15'
    }
  }
});

​
Custom Event

For non-standard tracking: 
permutive.track('CustomEvent', {
  action: 'button_click',
  element_id: 'signup-button',
  page_section: 'header'
});

​
Property Naming Conventions

Follow these conventions for consistent data:
ConventionExampleNotes
snake_casearticle_titlePreferred for custom properties
camelCasearticleTitleAlso supported
LowercasecategoryUse for simple properties
Property names are case-sensitive. category and Category are different properties. Be consistent across your implementation.

​
Reserved Property Names

Avoid these reserved property names:
  • time - Automatically set by SDK
  • session_id - Automatically set
  • view_id - Automatically set
  • client - Reserved for client context
  • geo_info - Reserved for geographic data

​
Nested Properties

You can nest properties up to 3 levels deep: 
permutive.track('Article', {
  content: {
    article: {
      metadata: {
        word_count: 1500,
        read_time: 7
      }
    }
  }
});
Deeply nested properties work in cohort building, but keep structures simple when possible for easier querying.

​
Arrays

Arrays are useful for multi-value properties: 
permutive.track('Article', {
  // Array of strings
  categories: ['technology', 'business'],

  // Array of numbers
  related_article_ids: [123, 456, 789],

  // Array of objects
  authors: [
    { name: 'Jane Smith', id: 'author-1' },
    { name: 'John Doe', id: 'author-2' }
  ]
});

​
Array Limitations

  • Maximum 100 items per array
  • Array items should be of consistent type
  • Nested arrays are not recommended

​
Page Properties vs Event Properties

Set via the web addon, applied to all events on the page:
permutive.addon('web', {
  page: {
    type: 'article',
    article: {
      title: 'Article Title',
      categories: ['news']
    }
  }
});

// These page properties are included in:
// - Pageview event
// - PageviewEngagement events
// - PageviewComplete event

​
Best Practices

// Good
permutive.track('Article', {
  article_category: 'technology',
  article_author: 'Jane Smith',
  is_premium_content: true
});

// Avoid
permutive.track('Article', {
  cat: 'tech',
  auth: 'JS',
  prem: 1
});
Use the same property names and types across all events:
// Consistent naming
permutive.track('Article', { article_id: '123' });
permutive.track('VideoPlay', { video_id: '456' });

// Avoid mixing
permutive.track('Article', { article_id: '123' });
permutive.track('Article', { articleId: '456' }); // Different convention!
Never include personally identifiable information:
// Good - use hashed or anonymized values
permutive.track('Login', {
  user_type: 'subscriber',
  account_age_days: 365
});

// Never do this
permutive.track('Login', {
  email: '[email protected]',  // PII!
  name: 'John Smith'          // PII!
});

// Good - correct types
permutive.track('Purchase', {
  price: 29.99,              // Number
  quantity: 2,               // Number
  product_name: 'Widget',    // String
  in_stock: true             // Boolean
});

// Avoid - incorrect types
permutive.track('Purchase', {
  price: '29.99',            // Should be number
  quantity: '2',             // Should be number
  in_stock: 'true'           // Should be boolean
});
Keep events focused with relevant properties only:
// Good - focused properties
permutive.track('ArticleRead', {
  article_id: '123',
  category: 'technology',
  read_percentage: 75
});

// Avoid - too many properties
permutive.track('ArticleRead', {
  article_id: '123',
  category: 'technology',
  // ... 50 more properties
});

​
Property Validation

The SDK validates properties before sending:
  • Invalid property types are converted or dropped
  • Very long strings may be truncated
  • Invalid JSON structures are rejected
Enable debug mode to see validation messages: 
?permutive_debug=true

​
Troubleshooting

Problem: Event tracked but properties missing in dashboard.Solutions:
  • Check property names match dashboard schema
  • Verify property types are correct
  • Enable debug mode to see what’s sent
  • Allow time for data processing
Problem: Numbers stored as strings or vice versa.Solutions:
  • Explicitly cast types before tracking
  • Use parseInt() or parseFloat() for numbers
  • Avoid string representations of numbers
Problem: Can’t build cohorts on deeply nested properties.Solution: Flatten structure or limit nesting to 2 levels:
// Instead of deep nesting
{ a: { b: { c: { d: 'value' } } } }

// Use flatter structure
{ a_b_c_d: 'value' }

Event Tracking

Track custom events

Pageview Tracking

Configure page properties

Cohorts

Build cohorts from properties

Connectivity Events

Event schema documentation