Skip to content
Docs
Measuring

Events

An event is one thing a visitor does on your site. Metrics count events, and a test is judged on a metric.

On this page 9

An event is one thing a visitor does: a page opens, a button is clicked, an order is completed. Your site tells us each time it happens.

Events are the bottom of the chain. A metric counts an event, and a test is judged on a metric, so nothing above works until the event below it is arriving.

What you get without doing anything

Once the tag is on your site, three events arrive on their own. They are marked Built in, collected automatically on every project, and a metric can use them straight away.

Event Arrives when
Page view A page loads, and again on each route change in a single-page app.
Session start The first activity of a session.
Engagement A scroll, a click, or time on the page past a threshold. What separates a bounce from a read.

Add an event yourself when you want something your site does not report on its own, such as an order being completed.

The nine ways an event is detected

Eight of them watch the page for you and need no developer. The ninth is code.

Detected by Fires when
Page view A matching URL loads, and again on each route change in a single-page app.
Click on an element A visitor clicks anything matching a CSS selector.
Click on a link A visitor clicks a link pointing at a matching URL.
Click on text A visitor clicks an element whose text matches. Survives a class rename, breaks on a copy change.
Form submit A matching form is submitted, not when it succeeds.
Element becomes visible A matching element first enters the screen.
Scroll depth The visitor scrolls past a percentage of the page. Fires once.
Time on page The visitor has been on a matching page for a number of seconds. Fires once.
Custom code You call track() yourself. The only one that can send a value.

Form submit is the one people get wrong. It fires when the form is sent, not when it worked. For "signed up", use the page they land on afterwards, or use Custom code.

How to set one up

  1. Open Events in the sidebar and click New event.
  2. Set How it is detected.
  3. Fill in what that choice asks for: a CSS selector, a URL, or a number.
  4. Type the Event name. The Key follows it as you type.
  5. Read the name and key back, then save.
Warning

An event cannot be renamed or removed once it exists. The key is stamped on every hit for ever, so a typo stays. Read both back before you save.

What each label means

Label What it means
How it is detected One of the nine ways. It decides which of the fields below you are asked for.
CSS selector For the three click kinds and Element becomes visible. What on the page to watch, such as #buy-now.
URL rule How to compare the address. Five options, listed below.
URL The address to match, such as example.com/checkout.
How far down the page For Scroll depth. A percentage from 1 to 100.
How long on the page For Time on page. Seconds, from 1 to 3600, and only while the tab is theirs.
Event name What you will call it everywhere else, such as "Order completed".
Key The short name stored with every hit, such as order_completed. We suggest one from the name.
Description Optional. One line on what the event means.
Event parameters For Custom code only. Extra details to keep alongside the event. Up to ten.

URL rules

Rule What it matches
Simple match Ignores the protocol, a leading www, a trailing slash and query parameters.
Exact match Character for character, query string included.
Contains The pattern appears anywhere in the URL. Use it to match a query parameter.
Wildcard Use * to stand for any run of characters: /blog/*/comments
Regular expression A JavaScript regular expression, tested against the whole URL.

Event parameter types

Type Use it for What a metric can do with it
Number A quantity, a score, a count Add it up or average it
Text A plan name, a category Count and group, never add up
Boolean A flag, true or false Count, never add up

Send your own event from code

Use Custom code when watching the page is not enough: the thing you care about happens after a check such as a payment clearing, or you want to record an amount. Custom code is the only kind that can send a value.

  1. Create the event with How it is detected set to Custom code.
  2. Add each detail you want to keep under Event parameters, giving every one a Parameter label, a Parameter key and a Parameter type.
  3. Open the event's Tracking code action and copy the line it shows.
  4. Paste it into your site where the action finishes, and put your real values in.

The Tracking code action shows the line with your parameters already in it:

js
splitstat.track('order_completed', {
  amount: 0,
  plan: ''
});

On your site, with real values:

js
splitstat.track('order_completed', {
  amount: 49.9,
  plan: 'pro'
});

Send the real number, not a string. Nothing has to be imported first: the tag already put that global on the page when you installed it.

Warning

Paste it where the action finishes, not where it starts. On the click of Pay you are counting attempts. On the page that confirms the order you are counting orders.

Good to know

  • Every parameter your code sends is stored, and shows in Live events. Only the ones the event declares can be used by a metric or a filter, so declare them before you build on them.
  • An event keeps at most 20 parameters. A parameter is dropped if its name is longer than 120 characters or its text is longer than 1,024 bytes, and an event whose parameters come to more than 8 KB in all is kept without them. The event itself is always counted.
  • A parameter a metric already reads cannot be removed. The screen shows you which ones those are.
  • If you will ever want value per visitor, the amount has to arrive from the start. We cannot work it out later from hits that never carried it.
  • Last seen on the Events list tells you the event is really arriving, and Read by counts the metrics built on it. A metric reading zero means either your change did nothing or the event never arrived. Check which before a test starts, not after.
  • Live events, linked from the top of the Events screen, shows hits as they come in. Open it and walk your own site to confirm a new event works.