Custom Definitions

Track data unique to your business by creating custom dimensions and metrics. Segment visitors, measure conversions, and answer questions standard analytics can't.

Overview

Custom definitions extend VeritaMetrics beyond standard web analytics. There are two types:

Dimensions — categorical values used to segment your data (e.g. "Author Name", "Product Category", "Experiment Variant").
Metrics — numeric values you want to aggregate (e.g. "Revenue", "Engagement Score", "Cart Total").

Each definition has a scope that determines how data is collected:

Event scope — attached to individual events (pageviews, clicks, custom events).
User scope — attached to a visitor session and persists across events.

Creating a Definition

Navigate to Site Settings → Custom Definitions in your dashboard. Click Create Definition and fill in the following fields:

Field	Description
Display Name	A human-readable label shown in the dashboard (max 50 characters).
Parameter Name	The key used in your tracking code. Must start with a letter, contain only lowercase letters, numbers, and underscores (max 40 characters). Cannot be changed after creation.
Scope	`event` or `user`. Cannot be changed after creation.
Data Type	`string`, `number`, or `boolean`. Cannot be changed after creation.
Aggregation Type	Required for numeric types. One of `sum`, `average`, `count`, `min`, or `max`.
Unit	Optional label for numeric values (e.g. "USD", "seconds").
Description	Optional internal note (max 200 characters).

Parameter Name Rules

Parameter names must match the pattern ^[a-z][a-z0-9_]*$. For example:

product_category ✓
cart_total ✓
experimentVariant ✗ — no uppercase
2nd_click ✗ — must start with a letter

Certain names are reserved for privacy protection and cannot be used, including email, name, phone, password, ssn, and credit_card.

Sending Custom Data

Once a definition is created, send data from your site using the VeritaMetrics tracker. Pass custom properties as the third argument to trackEvent:

Event-Scoped Data

Attach properties to specific events:

// Track a custom event with properties
window.verita('trackEvent', 'purchase', {
  product_category: 'Electronics',
  cart_total: 149.99
});

// Properties also work with page views
window.verita('trackPageView', {
  author_name: 'Jane Doe',
  content_type: 'blog_post'
});

Revenue Tracking

Use the built-in revenue helper for e-commerce:

window.verita('trackRevenue', {
  orderId: 'ORD-12345',
  amount: 79.99,
  currency: 'USD',
  products: ['SKU-001', 'SKU-042']
});

Quotas

Each plan has limits on how many active definitions you can create. Archiving a definition frees up quota while preserving historical data.

Plan	Event-Scoped	User-Scoped
Standard	50	25
Professional	100	50
Enterprise	Unlimited	Unlimited

Archiving & Lifecycle

Definitions cannot be deleted — they can be archived. This preserves historical data while freeing up quota. Archived definitions no longer appear in the dashboard filter dropdowns but their data remains accessible in exports and API queries.

The following fields are immutable after creation: parameterName, scope, dataType, and aggregationType. You can always update the display name, description, and unit.

Data Preview

After your site starts sending custom data, click any definition in the dashboard to see a live preview. The preview shows the top 50 values from the last 48 hours, including:

Value distribution and percentages for string dimensions.
Aggregated totals (sum, average, min, max) for numeric metrics.
Distinct visitor counts for user-scoped definitions.

← All Documentation Filtering & Segmentation →