Adding Custom Events — Featherweight Analytics

Custom events follow the same privacy model as everything else in Featherweight: no cookies, no personal data, and visitors cannot be tracked across days.

QUICK START

Install the tracking snippet

If you haven’t already. It’s shown in Settings → General for your site:

<script src="https://beta.featherweight.eu/featherweight.js" data-site-id="<your-site-token>"></script>

The snippet exposes a small global, window.featherweight.

Fire an event

Wherever the action happens:

featherweight.track('Signup');

For example, on a button:

<button onclick="featherweight.track('Newsletter Signup')">Subscribe</button>

See it in the dashboard

Open your site’s dashboard and switch the bottom widget to the Events tab. Each event name gets a row with its visitors, total events, and conversion rate (the share of the day’s visitors who fired it).

THE TRACK CALL

featherweight.track(name, options?)

ARGUMENTVALUE

name Required. The event’s name, e.g. Signup. Up to 120 bytes; an over-long name drops the event. Names are case-sensitive — Signup and signup are two different events, so pick one spelling and stick to it. The names pageview, departure and click are reserved for the tracker’s own beacons.

options.props Optional. A flat object of properties — see Properties below.

options.money Optional. Revenue carried by the event — see Revenue below.

featherweight.track('Purchase', {
  props: { plan: 'gold', period: 'annual' },
  money: { amount: 79.00, currency: 'EUR' },
});

Events are sent with navigator.sendBeacon, so a track call is fire-and-forget: it never blocks your page, and it still delivers when fired while the user is navigating away (a form submit, an outbound link).

One thing to know: there is no queue. featherweight.track exists only once the snippet has loaded, so code that might run earlier (or on pages where the script is blocked) should guard the call:

if (window.featherweight) featherweight.track('Signup');

PROPERTIES

Attach context to an event as a flat bag of key/value pairs:

featherweight.track('Download', { props: { file: 'report.pdf', format: 'pdf' } });

In the dashboard, clicking an event row on the Events tab drills into its properties — for each property key, the breakdown of values by visitors and events. Properties are also queryable through the API’s event_prop dimension, and can be matched by goal constraints.

What’s accepted

Values can be strings, numbers or booleans. Numbers and booleans are stored as their string form (42, true) — so 0 and false survive fine, but "42" and 42 are the same value.
A pair whose value is null, an array or a nested object is dropped; the rest of the event is unaffected.
Up to 30 properties per event (extras beyond the first 30 are dropped). Keys longer than 300 bytes and values longer than 2,000 bytes are truncated. Blank keys and blank values are dropped.

TIP

Choose values that repeat. Properties shine when a value is shared by many events — plan: gold, format: pdf — so the breakdown means something. Avoid values that are unique per user or per event (IDs, emails, timestamps): they make breakdowns useless, and personal data has no place in your analytics. Don’t send revenue as a property either — that’s what money is for.

REVENUE

An event can carry a monetary amount:

featherweight.track('Purchase', { money: { amount: 13.32, currency: 'EUR' } });

FIELDREQUIREDVALUE

amount yes A positive number in major units — 13.32 is thirteen euros and thirty-two cents, not 1,332 cents. Up to 3 decimal places (more are rounded).

currency no A 3-letter ISO 4217 code (EUR, USD, JPY). Omit it and the amount is treated as your site’s default currency, set in Settings → General.

NOTE

Validation is forgiving in the direction that protects your numbers: an invalid amount (zero, negative, non-numeric) means the event is recorded without revenue, and an invalid currency keeps the amount but treats it as the site default — a typo in the currency code never silently discards a sale.

Revenue is reported through revenue goals (see below): each goal reports in a currency you choose, and events recorded in other currencies are converted using daily exchange rates from the day of the event. Amounts also appear on the dashboard’s Properties view as a per-event “amount” facet.

EVENTS POWER GOALS

Custom events pair with Settings → Goals:

An event goal counts conversions for one event name — its visitors, completions and conversion rate get a row on the dashboard’s Goals tab, and clicking it filters the whole dashboard to that goal’s converters.
A revenue goal does the same for a money-carrying event, adding total and average revenue in the goal’s reporting currency.
Constraints (on an upgraded plan) narrow a goal to specific property values — e.g. count Purchase only where plan is gold.

Goals themselves are available on every plan; adding constraints requires an upgraded plan.

LIMITS AT A GLANCE

LIMITOVER THE LIMIT

Event name 120 bytes Event dropped

Properties per event 30 First 30 kept

Property key 300 bytes Truncated

Property value 2,000 bytes Truncated

money.amount > 0, ≤ 10¹² Revenue omitted, event kept

money.currency 3-letter ISO 4217 Treated as site default, amount kept

GOOD TO KNOW

Events are not pageviews. Custom events never inflate your visitor or pageview counts — they’re counted separately.
Visitors are daily uniques. As everywhere in Featherweight, a “visitor” on the Events tab is a daily unique; someone who fires an event on two different days counts twice. This is a deliberate part of the privacy model.
The API sees them too. The event dimension lists your events with visitors and completions; event_prop breaks down property values. Same numbers as the dashboard — see the API documentation.
Test with your own site first. Fire a test event from your browser’s console on a page with the snippet installed — it appears on the Events tab within moments.

BACK TO Documentation home

CUSTOM EVENTS