Skip to main content
Properties add context to events, turning simple actions into rich data points. Metadata captures technical details automatically. Together, they enable precise segmentation, attribution, and analysis.

​
Event Properties

Properties are key-value pairs that describe what happened during an event. Basic Event: 
datalyr.track('button_clicked');
Event with Properties: 
datalyr.track('button_clicked', {
  button_text: 'Sign Up Now',
  button_color: 'blue',
  location: 'hero_section',
  page_type: 'landing'
});

​
Property Types

​
Standard Properties

DATALYR recognizes common property names and handles them specially: Revenue Properties:
  • revenue or amount: Monetary value (number)
  • currency: Three-letter currency code (USD, EUR, GBP)
  • order_id: Unique order identifier (string)
  • transaction_id: Transaction reference (string)
Product Properties:
  • product_id: Product SKU or ID
  • product_name: Product title
  • product_category: Category or collection
  • product_price: Unit price
  • quantity: Number of items
  • variant_id: Product variant identifier
Page Properties:
  • page_url: Full page URL
  • page_path: URL path only
  • page_title: Document title
  • referrer: Previous page URL
User Properties:
  • email: User email address
  • name: User full name
  • phone: Phone number
  • user_id: Internal user identifier

​
Custom Properties

Add any properties relevant to your business: E-commerce: 
datalyr.track('product_viewed', {
  product_id: 'SKU-123',
  product_name: 'Wireless Headphones',
  product_category: 'Electronics',
  product_price: 99.99,
  product_vendor: 'TechBrand',
  in_stock: true,
  discount_applied: false,
  variant_options: ['Black', 'Medium']
});
SaaS: 
datalyr.track('feature_used', {
  feature_name: 'Export to CSV',
  usage_count: 5,
  subscription_plan: 'pro',
  workspace_id: 'ws_123',
  team_size: 12,
  is_trial: false
});
Media: 
datalyr.track('video_played', {
  video_id: 'vid_456',
  video_title: 'Product Demo',
  video_duration: 180,
  video_category: 'tutorials',
  playback_position: 0,
  quality: '1080p',
  autoplay: false
});
Lead Generation: 
datalyr.track('form_submitted', {
  form_id: 'contact_form',
  form_intent: 'demo_request',
  fields_completed: 5,
  time_to_submit: 45,
  company_size: '50-100',
  industry: 'SaaS'
});

​
Property Value Types

Properties support multiple value types: String: 
{
  product_name: 'Wireless Headphones',
  category: 'Electronics',
  status: 'active'
}
Number: 
{
  price: 99.99,
  quantity: 2,
  discount_percent: 15
}
Boolean: 
{
  in_stock: true,
  is_featured: false,
  autoplay: true
}
Array: 
{
  colors: ['Black', 'White', 'Blue'],
  tags: ['electronics', 'wireless', 'audio'],
  variant_options: ['Medium', 'Black']
}
Object (Nested): 
{
  product: {
    id: 'SKU-123',
    name: 'Wireless Headphones',
    price: 99.99
  },
  shipping: {
    method: 'express',
    cost: 9.99
  }
}
Date/Timestamp: 
{
  signup_date: '2025-09-29T10:30:45.123Z',
  trial_end: '2025-10-29',
  last_login: new Date().toISOString()
}

​
Automatic Metadata

DATALYR automatically captures metadata with every event:

​
Page Context

Automatically Captured: 
{
  "url": "https://example.com/products/headphones",
  "path": "/products/headphones",
  "search": "?utm_source=google",
  "title": "Wireless Headphones | Example Store",
  "referrer": "https://google.com/search?q=headphones"
}
Referrer Enrichment: 
{
  "referrer": "https://google.com/search?q=headphones",
  "referrer_host": "google.com",
  "referrer_path": "/search",
  "referrer_search": "?q=headphones",
  "referrer_source": "google"
}

​
Device Information

Screen Dimensions: 
{
  "screen_width": 1920,
  "screen_height": 1080,
  "viewport_width": 1400,
  "viewport_height": 900
}
Browser Capabilities: 
{
  "user_agent": "Mozilla/5.0...",
  "browser": "Chrome",
  "browser_version": "120.0",
  "os": "macOS",
  "os_version": "14.0",
  "device_type": "desktop"
}

​
Session Context

Session Data: 
{
  "session_id": "sess_1727634645123_a1b2c3d4",
  "session_duration": 45000,
  "session_page_views": 5,
  "session_events": 23,
  "session_start": 1727634645123,
  "time_since_session_start": 45000
}

​
Attribution Data

Marketing Attribution: 
{
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "summer_sale",
  "utm_term": "wireless headphones",
  "utm_content": "carousel_ad",
  "fbclid": "IwAR...",
  "source": "facebook",
  "medium": "cpc"
}
Landing Page: 
{
  "landing_page": "https://example.com/sale",
  "landing_path": "/sale"
}

​
Performance Metrics

Page Load Performance (pageview events): 
{
  "performance": {
    "dom_ready_time": 1200,
    "load_time": 2500,
    "first_contentful_paint": 800,
    "largest_contentful_paint": 1500
  }
}
Scroll Depth (scroll events): 
{
  "scroll_depth": 75
}

​
Fingerprinting Data

Device Fingerprint: 
{
  "fingerprint": "a1b2c3d4e5f6",
  "device_fingerprint": "a1b2c3d4e5f6"
}

​
Property Naming Conventions

Follow these conventions for consistent tracking:

​
Use snake_case

// Good
{
  product_name: 'Headphones',
  user_email: '[email protected]',
  order_total: 99.99
}

// Bad
{
  productName: 'Headphones',      // camelCase
  'user-email': '[email protected]', // kebab-case
  OrderTotal: 99.99                // PascalCase
}

​
Be Descriptive

// Good
{
  button_text: 'Add to Cart',
  button_location: 'product_page',
  button_color: 'blue'
}

// Bad
{
  text: 'Add to Cart',  // Too vague
  loc: 'product_page',  // Abbreviated
  color: 'blue'         // Ambiguous context
}

​
Use Consistent Names

// Good - Consistent across events
datalyr.track('product_viewed', {
  product_id: 'SKU-123',
  product_name: 'Headphones'
});

datalyr.track('product_added', {
  product_id: 'SKU-123',
  product_name: 'Headphones'
});

// Bad - Inconsistent naming
datalyr.track('product_viewed', {
  product_id: 'SKU-123',
  product_name: 'Headphones'
});

datalyr.track('product_added', {
  id: 'SKU-123',        // Different key name
  name: 'Headphones'    // Different key name
});

​
Avoid Reserved Keys

Don’t use these reserved property names:
  • user_id
  • userId
  • anonymous_id
  • anonymousId
  • visitor_id
  • session_id
  • event_id
  • timestamp
  • workspace_id

​
Property Limits

DATALYR enforces limits for performance and storage: Per Event:
  • Max 50 properties per event
  • Property names: 255 characters max
  • Property values: 10KB max
  • Total event size: 50KB max
Best Practices:
  • Keep property counts reasonable (10-20 is ideal)
  • Avoid deeply nested objects (max 3 levels)
  • Don’t include large text blocks in properties
  • Use arrays sparingly (max 100 items)

​
Sensitive Data Handling

Never send sensitive data: 
// BAD - Don't do this!
datalyr.track('checkout_completed', {
  credit_card_number: '1234-5678-9012-3456', // NO!
  cvv: '123',                                 // NO!
  ssn: '123-45-6789',                        // NO!
  password: 'user_password'                   // NO!
});
Hash sensitive identifiers: 
// Good - Hash or tokenize sensitive data
import crypto from 'crypto';

const emailHash = crypto.createHash('sha256')
  .update('[email protected]')
  .digest('hex');

datalyr.track('user_registered', {
  email_hash: emailHash,  // Hashed
  phone_hash: phoneHash   // Hashed
});
Safe user identification: 
// Good - Safe properties only
datalyr.identify('user_123', {
  email: '[email protected]',  // Safe
  name: 'John Doe',           // Safe
  plan: 'pro',                // Safe
  company: 'Acme Inc'         // Safe
});

​
Property Validation

DATALYR validates properties before sending: Valid Properties: 
// All valid
datalyr.track('button_clicked', {
  button_text: 'Sign Up',           // String
  clicks_count: 5,                   // Number
  is_primary: true,                  // Boolean
  tags: ['cta', 'hero'],            // Array
  metadata: { color: 'blue' },      // Object
  clicked_at: new Date().toISOString() // Date string
});
Invalid Properties (Dropped): 
// These will be dropped
datalyr.track('test_event', {
  valid_property: 'hello',
  undefined_prop: undefined,        // Dropped
  null_prop: null,                  // Dropped
  function_prop: () => {},          // Dropped
  symbol_prop: Symbol('test')       // Dropped
});

​
Enrichment Best Practices

Add Context to Every Event: 
// Good - Rich context
datalyr.track('video_played', {
  video_id: 'vid_123',
  video_title: 'Product Demo',
  video_duration: 180,
  video_category: 'tutorials',
  playback_position: 0,
  player_version: '2.0',
  quality: '1080p',
  autoplay: false,
  from_playlist: true,
  playlist_name: 'Getting Started'
});

// Bad - Minimal context
datalyr.track('video_played', {
  video_id: 'vid_123'
});
Use Properties for Segmentation: 
// Properties enable filtering/segmentation
datalyr.track('purchase_completed', {
  order_id: 'ORDER_123',
  revenue: 299.99,
  currency: 'USD',

  // Segmentation properties
  customer_type: 'returning',      // Segment by customer type
  acquisition_channel: 'facebook', // Segment by channel
  device_type: 'mobile',           // Segment by device
  country: 'US',                   // Segment by location
  product_category: 'electronics'  // Segment by category
});
Track User Intent: 
// Add intent signals
datalyr.track('form_submitted', {
  form_id: 'contact_form',
  form_intent: 'demo_request',     // User intent
  urgency: 'high',                 // Purchase readiness
  company_size: '50-100',          // Qualification
  industry: 'SaaS',                // Targeting
  fields_interacted: 8,            // Engagement level
  time_to_submit: 45               // Commitment level
});

​
Server-Side Properties

When tracking server-side, include additional context: 
// Node.js server-side tracking
await fetch('https://ingest.datalyr.com/events', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    workspaceId: 'ws_123',
    events: [{
      event_name: 'subscription_created',
      anonymous_id: 'anon_abc123',
      user_id: 'user_456',
      properties: {
        // Subscription details
        plan: 'pro',
        amount: 99,
        currency: 'USD',
        billing_cycle: 'monthly',
        trial_days: 14,

        // Server context
        server_timestamp: new Date().toISOString(),
        stripe_customer_id: 'cus_abc123',
        invoice_id: 'inv_456',

        // Additional metadata
        payment_method: 'card',
        referral_code: 'SUMMER2025',
        ip_address: req.ip // Optional for geo
      },
      timestamp: new Date().toISOString()
    }]
  })
});

​
Automatic Property Enrichment

DATALYR automatically enriches certain events: Pageview Events:
  • Performance metrics (load time, FCP, LCP)
  • Referrer data (domain, path, source)
  • Browser capabilities (user agent parsing)
Form Events:
  • Field interaction count
  • Time to submit
  • Form intent detection
E-commerce Events:
  • Product data (from page context)
  • Cart state (from DOM)
  • Platform detection (Shopify, WooCommerce, etc.)
Engagement Events:
  • Scroll depth (for scroll events)
  • Time on page
  • Click position

​
Property Schema Evolution

Properties can evolve over time as your tracking needs change: Initial Implementation: 
datalyr.track('button_clicked', {
  button_text: 'Sign Up'
});
Enhanced Version: 
datalyr.track('button_clicked', {
  button_text: 'Sign Up',
  button_id: 'cta-hero',       // New property
  button_location: 'hero',      // New property
  button_color: 'blue',         // New property
  variant: 'test_b'             // New property for A/B testing
});
DATALYR handles missing properties gracefully - old events remain queryable.

​
Next Steps

Events Overview

Learn about event tracking

Identity Calls

Link users across devices

Attribution Models

How conversions are attributed

Custom Events

Track custom events with SDK

​
Need Help?

Questions about properties? Check our troubleshooting guide or contact support.