# Automatic events

URL: https://pulsora.co/docs/core/auto-tracking

Record outbound link clicks, file downloads, form submissions, scroll depth and time on page without writing event code.

The tracker can send three kinds of events on its own. Each one is off until you turn it on, so turning it on is the only change to your traffic and your event count.

| Option | Event name | Properties |
| --- | --- | --- |
| `autoOutbound` | `Outbound Link: Click` | `url`: the link URL without its query string or hash |
| `autoDownloads` | `File Download` | `url`: the file URL without its query string or hash |
| `autoForms` | `Form: Submission` | `form`: the form's `id`, `name` or action path. `path`: the page it was on |

They're ordinary events: they count toward your plan's events like any other, show up in the **Events** panel and can be [goals](https://pulsora.co/docs/core/goals-and-funnels). Outbound clicks and downloads also get their own **Links** panel on the Analytics tab.

## Turn it on [#turn-it-on]

**npm**

```ts
pulsora.init({
  apiToken: 'pub_your_token',
  autoOutbound: true,
  autoDownloads: true,
  autoForms: true,
});
```

**React**: pass the same options in `config`.

```tsx
<PulsoraProvider config={{ apiToken: 'pub_your_token', autoOutbound: true, autoDownloads: true }}>
```

**Script tag**: list what you want in `data-auto`.

```html
<script defer src="https://cdn.jsdelivr.net/npm/@pulsora/core@1/dist/browser.js"
  data-token="pub_your_token"
  data-auto="outbound,downloads,forms"></script>
```

Needs `@pulsora/core` 1.2.0 or later.

## What counts [#what-counts]

- **Outbound**: a click on an `http` or `https` link to another hostname. Links to subdomains of your site count, because they're a different hostname. `mailto:`, `tel:` and in-page links don't.
- **Downloads**: a link whose path ends in a file extension from the list below, or any link with a `download` attribute. A download on another domain counts as a download, not an outbound click.
- **Forms**: every `submit` event of a `<form>`. Pulsora never reads field values, only the form's name and the page. Calling `form.submit()` from code fires no `submit` event, so use `form.requestSubmit()` if you want it counted.

URLs are sent without query strings or hashes, because those often carry signed download tokens, reset links or emails.

Middle clicks count. Right-click "open in new tab" can't be detected by browsers, so it doesn't.

Default download extensions: `pdf`, `xlsx`, `xls`, `docx`, `doc`, `txt`, `rtf`, `csv`, `exe`, `key`, `pps`, `ppt`, `pptx`, `7z`, `pkg`, `rar`, `gz`, `zip`, `avi`, `mov`, `mp4`, `mpeg`, `wmv`, `midi`, `mp3`, `wav`, `wma`, `dmg`, `iso`, `msi`. Pass your own list to replace it:

```ts
pulsora.init({ apiToken: 'pub_your_token', autoDownloads: ['pdf', 'epub'] });
```

## Skip an element [#skip-an-element]

Add `data-pulsora-ignore` to a link, a form or any element around them:

```html
<nav data-pulsora-ignore>
  <a href="https://status.example.com">Status</a>
</nav>
```

## As goals [#as-goals]

Use the event names as event goals, like `File Download`. To see which links and files were clicked, use the **Links** panel or the `outbound_links` and `file_downloads` breakdowns in the [stats API](https://pulsora.co/docs/api/stats). To count one specific file or form as its own goal, send a named event for it with `pulsora.event()`.

## Scroll depth and time on page [#scroll-depth-and-time-on-page]

Turn on `engagement` (or add `engagement` to `data-auto`) to measure, for every page view:

- **Scroll depth**: the deepest point the visitor reached, as a percentage of the page.
- **Time on page**: seconds the tab was visible, focused and in use. Time in a background tab or another window doesn't count, and the clock stops after 30 seconds without a scroll, key press or pointer movement.

```ts
pulsora.init({ apiToken: 'pub_your_token', engagement: true });
```

The tracker sends both when the visitor hides or leaves the page, and before the next page view in a single-page app. They're stored on the page view, not as events, so they don't count toward your plan. The **Top pages** table shows the averages in its **Scroll** and **Time** columns (each page view counts for at most 30 minutes in the Time average, so a tab left open doesn't skew it), and the stats API's `pages` breakdown returns them as `avg_scroll_depth` and `avg_engaged_seconds`. Page views from before you turned it on show a dash.

Nothing is stored in the browser: the values live in memory for the current page view only.

Needs `@pulsora/core` 1.3.0 or later.