Custom Events

Custom events let you track any user action that matters to your business. Signups, purchases, video plays, button clicks, file downloads, or anything else you want to measure. You define the event name, attach optional properties, and optionally include revenue data.

Custom events are sent using the clickport.track() JavaScript API, which is available automatically on any page where the Clickport tracker is installed.

The clickport.track() API

The tracker exposes a global clickport.track() function with three parameters:

clickport.track(name, properties, revenue)

• name (string, required): The event name. For example, 'Signup', 'Purchase', or 'Video Play'.
• properties (object, optional): Key-value pairs with additional context. For example, { plan: 'pro', source: 'homepage' }.
• revenue (object, optional): Revenue data with amount (number) and currency (string, defaults to 'USD').

Basic usage

At its simplest, call clickport.track() with just an event name:

Tracking a button click

<button onclick="clickport.track('CTA Click', { button: 'hero-signup' })">
  Get Started
</button>

Tracking a form submission

document.getElementById('signup-form').addEventListener('submit', function() {
  clickport.track('Form Submit', { form: 'newsletter' });
});

Tracking with a framework (React, Vue, etc.)

// React example
function handlePurchase(product) {
  window.clickport.track('Purchase', {
    product: product.name,
    category: product.category
  }, {
    amount: product.price,
    currency: 'EUR'
  });
}

Properties

Properties let you attach structured data to an event. Pass them as a plain JavaScript object in the second parameter. Each key becomes a property name, and each value becomes the property value.

clickport.track('Video Play', {
  title: 'Product Demo',
  duration: '3:24',
  autoplay: 'false'
});

Properties appear in the dashboard as expandable rows under each event name. You can see which property values are most common and how many times each was recorded.

Property limits

• Maximum 30 properties per event. If you pass more than 30 keys, the extra properties are silently dropped.
• Values are truncated to 2,000 characters. If a value exceeds this length, it is cut off at 2,000 characters.
• All values are converted to strings. Numbers, booleans, and other types are automatically converted. For example, { count: 42 } becomes { count: '42' }.

Revenue tracking

The third parameter lets you attach revenue data to any custom event. This is useful for tracking purchases, donations, subscriptions, or any action with a monetary value.

The revenue object accepts two fields:

• amount (number, required): The monetary value. Use decimal notation for cents, for example 49.99.
• currency (string, optional): A three-letter currency code. Defaults to 'USD' if not specified.

Custom events in the dashboard

Custom events appear in the Goals panel under the Events tab. Each unique event name is listed as a row with the total count for the selected date range. Click the arrow next to an event name to expand it and see property breakdowns.

In this example, the "Purchase" event has been expanded to show property breakdowns. The other events show a collapsed arrow, indicating they also have properties you can explore.

Clickport automatically detects new event names as they arrive. There is no setup needed in the dashboard to start seeing your events. Just call clickport.track() and the event will appear in the Events tab.

Using custom events with goals

You can create goals that trigger on custom events. This lets you track conversion rates, compare periods, and see custom events reflected in your KPIs.

To set up a custom event goal, go to Settings > Goals and create a new goal with the type set to Custom Event. Enter the event name exactly as you pass it to clickport.track().

Once configured, the goal appears in the Goals sub-tab with a conversion count and rate. Custom event goals also feed into the Conversions and Conv. Rate KPIs at the top of the dashboard.

How it works under the hood

When you call clickport.track(), the tracker sends a lightweight request to the Clickport API. The event is stored with your session data and linked to the current page visit. Here is what gets sent:

• Event type: 'custom' (internal compact key: 'e')
• Event name: the name parameter you passed
• Properties: stored as parallel arrays (meta_keys and meta_values) in ClickHouse
• Revenue: stored as revenue_source_amount and revenue_source_currency

Custom events use beacon mode (fetch with keepalive: true) for reliability. This ensures events are delivered even if the user navigates away immediately after the action.

Limits and best practices

• Keep event names consistent. Use the same name string everywhere you track the same action. 'Purchase' and 'purchase' are treated as separate events.
• Use properties for variants, not separate event names. Instead of track('Signup Pro') and track('Signup Free'), use track('Signup', { plan: 'pro' }) and track('Signup', { plan: 'free' }). This keeps your Events tab clean and lets you use property breakdowns.
• Avoid high-cardinality property values. Properties like user IDs or timestamps create too many unique rows. Stick to values with a bounded set (plan names, categories, button labels).
• Revenue amounts should be numbers. Pass 49.99, not '$49.99'. The currency symbol is handled by the currency field.
• Custom events count toward your monthly pageview quota. Each clickport.track() call counts as one event against your plan limit, the same as a pageview.

Debugging

To verify your custom events are being sent, open your browser's developer tools and check the Network tab. Filter for requests to /api/event. You should see a POST request with the event data in the request body.

Look for these fields in the payload:

• t: "e" confirms the event type is "custom"
• n: "YourEventName" is the event name
• mk: [...] is the array of property keys
• mv: [...] is the array of property values
• ra: 49.99 is the revenue amount (if set)
• rc: "USD" is the revenue currency (if set)

Events appear in the dashboard within a few seconds of being sent. If you do not see your event in the Events tab, check that the tracker script is loaded and that the event name matches what you expect.