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.trackcomes 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-outboundanddata-track-formsattributes 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
signuptoday andsign_upnext month show up as two different events. - Name the action, not the page.
add_to_cart,book_callandnewsletter_subscribesay what the visitor did. - Keep
paymentfor real sales. Radar treats an event named exactlypaymentin 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: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.
Send the event after the action succeeds
Callvisitors.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 theasync 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.
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.trackline: an earlyreturn, an error just before, or a missingvisitorsobject 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: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.