Skip to main content
A custom event is an action you choose to record in Radar: a sign-up, a click on a button, a form sent. The Radar script records page views by itself. For everything else, your site’s code calls visitors.track at the moment the action happens. This guide covers the call, its arguments, the right moment to send it, and how to check that it arrived. Not a developer? The Help Center article on custom events explains the same feature and how to read its report, without code.

Before you start

  • Install the Radar script. visitors.track comes with the script, so the script has to be on every page that sends an event. See install the script, then check your installation.
  • Know what the script already tracks. Page views arrive on their own, and the data-track-outbound and data-track-forms attributes of the tag turn on the tracking of outbound link clicks and form submissions. See how the script works.
  • Check your plan. Custom events are available from the Starter plan. Compare plans on the pricing page.
The JavaScript object is called visitors. That is the right name: do not replace it with radar in your code.

The call

A third argument exists for one case only: the amount of a sale. See track revenue.

Choose your event names

  • Keep names short and stable. Radar groups events by name, so signup today and sign_up next month show up as two different events.
  • Name the action, not the page. add_to_cart, book_call and newsletter_subscribe say what the visitor did.
  • Keep payment for real sales. Radar treats an event named exactly payment in a special way: it is the event that carries a sale and the buyer’s name. See track revenue.

Add properties

Properties are optional. You choose the keys and the values:
A few keys have a meaning for Radar: email, name, first_name and last_name describe the visitor, not the event. An email sent on any event identifies the visitor. See identify visitors.
Only put an email in the properties when you mean to identify the visitor. Identifying people has consequences for consent. See privacy, cookies and GDPR.

Send the event after the action succeeds

Call visitors.track once the action has really happened, not when the visitor tries. A form is the classic trap. If you send the event on the click of the submit button, you also count every attempt that fails: a missing field, a wrong email, a server error. Your report then shows more sign-ups than you really got. Wait for the success, then send the event.

Examples

Sign-up

Send the event only when the account exists. In this example, createAccount stands for your own sign-up code.

Button click

A button that opens something or starts a download has no success or failure to wait for. Send the event on the click.

Form

Send the form yourself, check the answer, then send the event. In this example, /api/contact stands for the address your own form posts to.

Protect your code when the script is missing

The Radar script loads with the async attribute, which means the browser does not wait for it. It can also be held back by a consent tool or blocked by a browser extension. In those cases the visitors object does not exist, and a direct call stops your code with an error. If the event sits in code that must keep running, such as a sign-up or a checkout, test for the object first:

Check that the event arrives

1

Publish your change

Test on your published site, not on a copy running on your own computer.
2

Trigger the action yourself

Do what a visitor would do: fill in the form, click the button, finish the sign-up.
3

Look at the Custom Events block

Open your project in Radar. On the overview, the Custom Events block lists one line per event name, with two numbers: People, the number of different visitors who triggered it, and Events, the number of times it was triggered.
You can also read the same list from your own tools with the Radar API. An API key is a secret code that lets a program read your data. Create one in your project settings, under API, and keep it on your server, never in the code of a web page.
Each entry of the answer carries event_name, people and events. See the custom events endpoint. The Radar API is available from the Pro plan.

The event does not show up

  • No page views either. The problem is the installation, not your event. A wrong project key (the pk_ value in the script) leaves the dashboard empty. Go through I installed the script but I see no data.
  • Page views arrive, the event does not. Check that your code reaches the visitors.track line: an early return, an error just before, or a missing visitors object all skip it. The browser console shows the error.
  • Still nothing. Contact support from the chat in your dashboard or at hello@taap.it.

Use your events in a funnel

A funnel is a path you define step by step, for example landing page, then form sent, then call booked. Radar shows how many visitors go from each step to the next. You build funnels in the Radar dashboard, with no extra code: each step is either a page or one of your custom events. Funnels are available from the Starter plan, like custom events. Your part as a developer is to send one event for each action that has no page of its own:
Once both events arrive, they can be picked as funnel steps. See build a conversion funnel.

Good to know

  • Every event counts. Each custom event counts toward the events your plan includes each month. See plans and events.
  • No webhooks. Radar does not notify your systems when an event happens. To use events elsewhere, read them with the Radar API.
  • Deleting a project deletes its events. Deleting a Radar project deletes all its data, custom events included.

Next steps

Identify visitors

Attach an email or a name to a visitor with the same call.

Track revenue

Send a sale to Radar from Stripe or from your own payment page.