Custom Properties

What are Properties?

Properties are custom key-value pairs attached to events via the metadata field. They allow you to capture any additional context about an event - user attributes, transaction details, feature flags, A/B test variants, and more.

Sending Properties with Events

Include properties in the metadata object when tracking events:

import { Serla } from './lib/serla';

const serla = new Serla('YOUR_API_KEY');

// Identify user
serla.identify('user_123');

// Track with custom properties
await serla.send('purchase_completed', {
  amount: 29.99,
  currency: 'USD',
  plan: 'pro',
  billing_cycle: 'monthly',
  trial: false,
  payment_method: 'card',
  coupon_code: 'SAVE20'
});

Property Types

Serla automatically detects and categorizes property types:

Property Discovery

Serla automatically discovers properties from your events and catalogs them in the Properties dashboard. For each property, you'll see:

• Property Path: The JSON path to the property (e.g., metadata.plan)
• Type: Detected data type (string, number, boolean, etc.)
• Sample Values: Recent examples of values for this property
• Unique Count: Approximate number of unique values
• Last Seen: When this property was last used

Property Configuration

Once discovered, you can configure properties for better analytics:

Display Name & Description

Add human-readable names and descriptions to make properties easier to understand:

Revenue Properties

Mark properties that represent revenue for automatic revenue tracking:

Category Properties

Mark properties used for grouping and segmentation:

Dimension Properties

Mark properties used for filtering in analytics:

Using Properties in Queries

Filter Events by Property

curl -X GET "https://serla.dev/api/analytics/events?projectId=proj_123&eventNames=purchase_completed&filters=metadata.plan:pro" \
  -H "Authorization: Bearer YOUR_API_KEY"

Aggregate by Property

curl -X GET "https://serla.dev/api/analytics/stats?projectId=proj_123&groupBy=metadata.plan" \
  -H "Authorization: Bearer YOUR_API_KEY"

Property Best Practices

• Use consistent naming: snake_case for property names (e.g., user_id, plan_type)
• Keep metadata flat when possible: Avoid deep nesting for better query performance
• Use descriptive names: subscription_plan instead of plan
• Standardize values: Use lowercase for enum-like values ("pro" not "Pro")
• Don't include PII: Avoid sending sensitive data like full names, addresses, or SSNs
• Keep metadata small: Limit to essential data - metadata is stored as JSON and counts toward event size

Reserved Properties

These top-level fields are reserved and automatically handled by Serla:

Common Property Examples

E-commerce

{
  "eventName": "purchase_completed",
  "metadata": {
    "order_id": "ord_abc123",
    "amount": 149.99,
    "currency": "USD",
    "items_count": 3,
    "shipping_method": "express",
    "payment_method": "card",
    "discount_code": "SAVE20",
    "is_first_purchase": true
  }
}

SaaS Application

{
  "eventName": "feature_used",
  "metadata": {
    "feature_name": "custom_dashboards",
    "plan": "pro",
    "trial": false,
    "organization_id": "org_xyz789",
    "workspace_size": 12,
    "ab_test_variant": "variant_a"
  }
}

Content Platform

{
  "eventName": "content_viewed",
  "metadata": {
    "content_id": "article_456",
    "content_type": "blog_post",
    "category": "engineering",
    "author_id": "author_123",
    "word_count": 1500,
    "reading_time": 7,
    "is_premium": false
  }
}