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

# track()

> Send a custom behavioural event that can be used in Zenstep targeting rules.

## Signature

```typescript theme={null}
window.zenstep.track(
  event: string,
  data?: Record<string, unknown>
): void
```

***

## Parameters

<ParamField path="event" type="string" required>
  The name of the event. Use snake\_case by convention.

  **Max length:** 255 characters.

  **Examples:** `"feature_used"`, `"export_clicked"`, `"onboarding_completed"`, `"video_watched"`
</ParamField>

<ParamField path="data" type="object">
  Optional properties attached to this event. Values can be any JSON-serialisable type.

  ```typescript theme={null}
  { feature: "csv_export", from_page: "/analyze" }
  ```
</ParamField>

***

## Examples

### Simple event

```javascript theme={null}
window.zenstep?.track("onboarding_started");
```

### Event with properties

```javascript theme={null}
window.zenstep?.track("feature_used", {
  feature: "csv_export",
  from_page: window.location.pathname,
  flow_count: 12,
});
```

### Track a video watched

```javascript theme={null}
videoPlayer.addEventListener("ended", () => {
  window.zenstep?.track("video_watched", { video_id: "intro-tour" });
});
```

***

## Using track events in targeting

Tracked events unlock the **Behavior** targeting rule type. You can show a flow only after a user has performed an action a specific number of times.

**Examples:**

| Rule                                     | Description                                   |
| ---------------------------------------- | --------------------------------------------- |
| `feature_used` ≥ 3 times                 | Show "You're a power user!" flow after 3 uses |
| `export_clicked` = 0 times (last 7 days) | Show CSV export tooltip if never exported     |
| `onboarding_started` > 0 times           | Skip re-showing getting started flow          |

To create a behavior rule: in the flow editor, open **Targeting → Add rule → Behavior**.

***

## Event storage

Track events are:

1. Sent to `POST /api/v1/events` in batches
2. Stored in your Zenstep analytics (visible in the **Analyze** section of the dashboard)
3. Used by the targeting engine to evaluate behavior rules on the next page load or navigation

Events are stored with a HMAC-SHA256 hash of the `userId` — no raw PII is stored.

***

## Difference from analytics events

`track()` records **custom behavioural events** — things the user does in your app.

Zenstep's built-in analytics events (`view`, `complete`, `dismiss`, `skip`) are emitted automatically when a user interacts with a flow. You don't need to call `track()` for those.

Use `track()` when you want to:

* Trigger flows based on in-app actions (not just URL patterns)
* Build behavioral segments
* Record custom conversion milestones