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

# Goals

> Record conversions from your website and use them in segments and automations.

![Goals section with a card per goal showing count, conversion rate, total and median value against the previous period](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goals.png)

A goal is something worth counting: a signup, a purchase, a demo request. Your site reports it, and Web Analytics records it against the visit that produced it.

## Recording a Goal

```javascript
NotifuseAnalytics.trackGoal({ action: 'purchase', type: 'purchase', value: 49.9 })
```

| Field        | Required | Notes                                                                                                           |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `action`     | Yes      | The goal name, up to 100 bytes — 100 ASCII characters, fewer for accented or non-Latin text.                    |
| `type`       | Yes      | What kind of conversion this is: `purchase`, `subscription`, `lead`, `signup`, `booking`, `trial` or `other`.   |
| `value`      | No       | A non-negative number — revenue, or whatever you are totalling.                                                 |
| `properties` | No       | Up to 50 values of your own, 1024 bytes per value and 8 KB in total, keys included. They are stored as strings. |

`type` is required because only your site knows whether a conversion is a sale or
a lead, and the goal-based segment conditions filter on it. `trackGoal` rejects
when `type` is missing or isn't one of these values, in lowercase, so catch the
error if you wait for `trackGoal` before redirecting. Use `other` when none of
the rest fit.

The current page path and its position in the visit are attached for you, so a goal always knows where it happened.

> [!NOTE]
>
> Goals are sent immediately rather than waiting for the next heartbeat. A conversion on a page the visitor is about to leave still arrives.

> [!WARNING]
>
> A negative `value` makes the whole goal invalid, and the goal is discarded — name and all, not just the number. This differs from the [Custom Events](https://www.notifuse.com/docs/features/custom-events.md) API, which deliberately accepts negative values for refunds and chargebacks.

You do not declare goals anywhere first. The Goals tab lists whatever names your site has actually sent, ordered by conversions, showing up to the 30 most-converted goals for the period and filters you have applied.

### Values From a Tag Manager or Plain JavaScript

A snippet or a tag manager often passes values read from the page, so `trackGoal` converts the common types for you:

- A `value` given as a string written like a JSON number, such as `'49.90'` or `'120'`, is stored as a number. `'49,90'`, `'1,299.00'`, `'€49.90'` and `'.5'` are not, and such a goal is left out, as described below.
- A `value` of `NaN` (what `parseFloat('€49.90')` returns), an infinite number, `null` or an empty string records the goal without a value and without a warning. The Goals tab and the reports count such a goal as 0 in average and median values.
- Numbers and booleans in `properties` are stored as strings and a `Date` as its ISO string. `null`, `NaN`, an infinite number and an invalid `Date` are stored as an empty string, and an `undefined` entry is left out.
- When `properties` is `false`, `''` or `0`, as `coupon && { coupon }` gives without a coupon, the goal is recorded without properties.

A goal whose data still can't be recorded is left out with a warning in the browser console, and the call still resolves, so a page that waits for `trackGoal` before redirecting still redirects. That covers a missing, blank or non-string `action` or one over 100 bytes, a `value` that isn't a number or is outside 0 to 1e12, and `properties` that are an array, a non-empty string, `true` or a number other than `0` and `NaN`, hold an object or an array, or go over the limits above. The rest of the visit keeps recording.

A `Map`, `FormData` or `URLSearchParams` has no fields of its own, so a goal given one as `properties` is recorded without properties and without a warning: pass `Object.fromEntries(…)` of it instead, leaving out any file field, whose value is an object.

## What a Goal Produces

The eye on a goal's card opens its dashboard full width. Every figure on it counts conversions of that goal only.

![Goal dashboard for add_to_cart: previous and next goal buttons, the period compared, the Count, Conv. Rate, Total Value and Median Value strip, an annotated daily chart, a day-and-hour heatmap, and the Top Sources, Top Campaigns and Devices cards](https://www.notifuse.com/docs/assets/screenshots/web_analytics/goal_dashboard.png)

- **The bar** goes back to Goals, moves to the previous or next goal of the grid with the arrows or with **K** and **J**, and shows the period and the one it is compared to. Both are set on the Goals tab.
- **Filtered by** lists the filters applied, each removable. They are the filters of the whole Web Analytics section: clicking a row or a country in the dashboard adds one there too.
- **The KPI strip** gives Count, Conv. Rate, Total Value and Median Value, against the comparison period. Clicking Count, Total Value or Median Value charts it.
- **Conv. Rate** is the goal's conversions divided by the sessions of the period, as on the goal's card. It counts goal events, not converting sessions, so a goal reached twice in a session counts twice and the rate can pass 100%. Its tooltip warns that it includes all traffic, whatever the visitor came for.
- **The chart** follows the granularity you pick on it and carries your [annotations](https://www.notifuse.com/docs/web-analytics/annotations.md), next to a heatmap of the goal by day and hour.
- **The cards** break the conversions and their value down: Top Sources (referrers, channels, channel groups), Top Campaigns (campaigns, sources, mediums, leaving out conversions without one), Devices (devices, browsers, OS), Countries (map and list), Landing pages (landing pages and goal pages), and a card for your custom dimensions that have a name.

In the reports, goals give you the Goals, Total Goal Value, Avg Goal Value, Median Goal Value and Converting Sessions measures, and the Goal Name, Goal Path and Goal Value dimensions. At the session level, Sessions with Goals and Goal Value let you compare channels by what they actually converted rather than by traffic.

For an **identified** visitor, a goal also becomes a custom event on their contact timeline — which is what makes it reachable from segments and automations. See [Identifying Visitors](https://www.notifuse.com/docs/web-analytics/identifying-visitors.md).

## Goal Names on the Contact Timeline

A goal that reaches a contact timeline is normalised first: lowercased, with anything outside ASCII `a–z`, `0–9`, `.` and `/` collapsed to a single `_`, leading and trailing `_` trimmed, and the result cut at 100 characters. So `Trial Started` arrives as `trial_started`, and it is that name an automation or segment matches on.

> [!WARNING]
>
> The kept set is ASCII-only, so accented and non-Latin letters are dropped rather than transliterated: `Café` arrives as `caf`. A name with no ASCII letters or digits at all — `購入`, say — normalises to nothing and never reaches the timeline. The goal is still recorded and still appears in the reports; only the timeline copy is skipped. Use ASCII goal names if you intend to segment or automate on them.
>
> This is also narrower than the naming rule for events sent through the [Custom Events](https://www.notifuse.com/docs/features/custom-events.md) API, which allows hyphens: `black-friday` sent from a web goal becomes `black_friday`.

## Using Web Goals in Segments

A web goal is as expressive as a custom event created through the API, because it
carries the same three things: a name, a value and a type.

- The **Custom Events Goal** condition matches web goals, under a specific type or
  under **All types**, and counts, sums and averages their value.
- An **automation** can trigger on a custom event with the goal's normalised name.

> [!NOTE]
>
> The type is asserted by your site, not verified by Notifuse — the same page also
> chooses the goal's name and value. Read revenue reporting with that in mind, as
> you would for events sent through the API.

## Limits

- Up to 100 goals of one session are bridged to the contact timeline per write batch. Goals beyond that within the same batch are dropped from the timeline permanently, and the counter restarts on each batch — so a long visit that keeps converting can end up with more than 100 timeline entries in total. Either way the visit itself keeps recording; the cap only affects the timeline copy.
- A goal older than 24 hours is not bridged to a timeline. A visitor whose browser was offline for a day comes back with their visit intact, without firing "you just did this" automations a day late.
- A goal with a value above 1e12, a name over 100 bytes, properties over 50 keys, 1024 bytes in one value or 8 KB in all with their keys, a property that holds an object or an array, or a NUL character (`\u0000`) in its name or properties is dropped — the goal alone, never the rest of the visit.

## Notes

- Goals from anonymous visitors are recorded and reported normally. Only the timeline copy needs an identity.
- Bridged events carry the visit's context as properties — session id, path, landing path, UTM source / medium / campaign, device and country — alongside your own. Those keys are set by Notifuse and overwrite properties of the same name.
- A currency, an order id, or anything else the conversion carries goes in `properties` — those are sent and stored. There is no dedicated `currency` field: `goal_value` is a plain number, so if you record more than one currency, group your reports by the currency property rather than summing values across them.
- [API Reference](https://www.notifuse.com/docs/api-reference.md)
