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:

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
});

To attach page-scoped data (e.g. author or content type), send it as a custom event — trackPageView does not accept custom properties.

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']
});

Without Code (HTML Attributes)

You can send custom events and properties without writing any JavaScript. Add a data-verita-event-name attribute to any clickable element, and attach properties with data-verita-prop-* attributes — the part after data-verita-prop- becomes the property key:

<button
  data-verita-event-name="signup"
  data-verita-prop-plan="pro"
  data-verita-prop-source="pricing"
>
  Create account
</button>

Clicking this button records a signup event with the properties plan: "pro" and source: "pricing". Hyphenated suffixes become snake_case (data-verita-prop-cart-total → cart_total), and attribute values are always sent as strings.

Viewing Custom Events in the Dashboard

Custom events and their properties surface in the dashboard in three places:

• Definition preview — open any definition in Site Settings → Custom Definitions to see its live preview: the top values from the last 48 hours.
• Custom Report widget — add the Custom Report widget to your dashboard, then pick a dimension to break events down by a property value (e.g. plan, product_category). Only string dimensions appear in this picker — numeric metrics are aggregated in the definition preview instead.
• Goals — create a goal triggered by a custom event name to track completions and conversion rate over time. See Goals & Data Export.

To break an event down by one of its properties, that property must first be registered as a string dimension. There is no automatic discovery of event properties — this is deliberate, so that personal data is never silently collected.

Recipe: Measuring Satisfaction Signals

Engagement signals (clicks, scroll depth, active time) are captured automatically, but outcome signals that happen after the visit — an order being fulfilled, or a customer leaving a review — have to be sent as custom events. Two common ones:

Fulfilled outcome

Fire an event when an order ships or a booking completes. It then appears alongside your other events and can drive a goal:

window.verita('trackEvent', 'order_fulfilled', {
  order_id: 'ORD-12345'
});

Review score

Send the rating as a property, then register score as a string dimension so the Custom Report can split positive from negative:

window.verita('trackEvent', 'review_submitted', {
  score: '5'
});

Define a dimension with parameter name score and data type string, then add the Custom Report widget and select it to see the distribution of scores. Use a string (not numeric) dimension when you want a breakdown by each value rather than an average.

Quotas

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

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.