> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taap.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Send custom events with visitors.track

> Call visitors.track from your site's code to record sign-ups, button clicks and form submissions in Radar, then check that each event arrives.

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](https://docs.taap.it/help/radar/features/custom-events.md) 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](https://docs.taap.it/help/radar/install-the-script.md), then [check your installation](https://docs.taap.it/help/radar/check-your-installation.md).
* **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](https://docs.taap.it/radar/how-the-script-works.md).
* **Check your plan.** Custom events are available from the Starter plan. Compare plans on the [pricing page](https://taap.it/pricing).

> [!NOTE]
>
> The JavaScript object is called `visitors`. That is the right name: do not replace it with `radar` in your code.

## The call

```javascript theme={null}
visitors.track("signup", {
  plan: "pro",
  source: "footer",
});
```

| Argument | Type | Required | What it is |
| - | - | - | - |
| Event name | string | Yes | The name the event gets in your reports, for example `signup` or `add_to_cart`. |
| Properties | object | No | Details about this one event, written as pairs of a key and a value, for example `plan`, `price` or `source`. |

A third argument exists for one case only: the amount of a sale. See [track revenue](https://docs.taap.it/radar/guides/track-revenue.md).

## 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](https://docs.taap.it/radar/guides/track-revenue.md).

## Add properties

Properties are optional. You choose the keys and the values:

```javascript theme={null}
visitors.track("add_to_cart", {
  product: "running-shoes",
  price: 89,
  source: "product_page",
});
```

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](https://docs.taap.it/radar/guides/identify-visitors.md).

> [!WARNING]
>
> 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](https://docs.taap.it/help/radar/privacy-and-consent.md).

## 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.

| Action | When to call `visitors.track` |
| - | - |
| Sign-up, login, booking, form | After your server confirms the action. |
| Click on a button or a link that sends nothing to a server | On the click itself. The click is the action. |
| Purchase | After the payment is confirmed. See [track revenue](https://docs.taap.it/radar/guides/track-revenue.md). |

## Examples

### Sign-up

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

```javascript theme={null}
async function onSignupSubmit(event) {
  event.preventDefault();

  const result = await createAccount(new FormData(event.target));
  if (!result.success) return;

  visitors.track("signup", {
    plan: "pro",
    source: "pricing_page",
  });
}
```

### 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.

```html theme={null}
<button id="download-brochure">Download the brochure</button>

<script>
  document
    .getElementById("download-brochure")
    .addEventListener("click", function () {
      visitors.track("brochure_download", {
        location: "hero",
      });
    });
</script>
```

### 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.

```javascript theme={null}
const form = document.querySelector("#contact-form");

form.addEventListener("submit", async function (event) {
  event.preventDefault();

  const response = await fetch("/api/contact", {
    method: "POST",
    body: new FormData(form),
  });
  if (!response.ok) return;

  visitors.track("contact_form_submit", {
    form: "contact",
  });
});
```

## 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:

```javascript theme={null}
if (typeof visitors !== "undefined") {
  visitors.track("signup", { plan: "pro" });
}
```

## 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.

```bash theme={null}
curl -X GET 'https://taap.it/api/v1/radar/custom-events?limit=20' \
  -H 'Authorization: Bearer taapit_your_api_key_here'
```

Each entry of the answer carries `event_name`, `people` and `events`. See the [custom events endpoint](https://docs.taap.it/api-reference/radar/custom-events.md). 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](https://docs.taap.it/help/radar/no-data.md).
* **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](mailto: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:

```javascript theme={null}
visitors.track("contact_form_submit", { form: "contact" });

// Later, when the visitor books a call
visitors.track("book_call", { source: "landing" });
```

Once both events arrive, they can be picked as funnel steps. See [build a conversion funnel](https://docs.taap.it/help/radar/features/funnels.md).

## Good to know

* **Every event counts.** Each custom event counts toward the events your plan includes each month. See [plans and events](https://docs.taap.it/help/radar/plans-and-events.md).
* **No webhooks.** Radar does not notify your systems when an event happens. To use events elsewhere, read them with the [Radar API](https://docs.taap.it/api-reference/radar/introduction.md).
* **Deleting a project deletes its events.** Deleting a Radar project deletes all its data, custom events included.

## Next steps

> [card] [Identify visitors](https://docs.taap.it/radar/guides/identify-visitors.md)
>
> Attach an email or a name to a visitor with the same call.

> [card] [Track revenue](https://docs.taap.it/radar/guides/track-revenue.md)
>
> Send a sale to Radar from Stripe or from your own payment page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.