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

# track()

> Send a Bily event or your own application event with an optional payload.

Use `track()` to record an outcome with a known Bily name or your own non-empty event name.

## Send an event

```typescript theme={null}
function track(event: BilyEvent, payload?: BilyPayload): void;
```

## Track a known outcome

```typescript theme={null}
import { track } from "@bilyai/js";

track("Product Viewed", {
  products: [
    {
      id: "product_123",
      name: "Everyday Tee",
      price: 39,
      currency: "USD",
    },
  ],
});
```

## Track an application outcome

```typescript theme={null}
track("integration_connected", {
  integration_id: "integration_456",
  integration_type: "crm",
});
```

Use stable snake\_case names for application events. You still get autocomplete for known Bily names.

## Know what Bily adds

When the SDK prepares a browser event, it adds:

* A Bily browser tracking ID when one is available.
* An ISO timestamp when `ts` is not already a string.
* A generated event ID when `event_id` is empty or absent.
* The browser source for the event.

Provide `event_id` when the same outcome needs one identifier across systems.

## Track before loading finishes

Call `track()` before `init()` or while Bily loads. The SDK keeps those calls in memory until loading succeeds.

The queue holds 100 calls by default. Set a limit from 1 to 1,000 with `init({ maxQueueSize })`.

When the queue is full, the SDK removes the oldest call before it adds the newest.

## Handle errors without interrupting the app

* An empty or whitespace-only event name is ignored.
* A browser delivery failure does not throw from `track()`.
* With `debug: true`, Bily logs a warning for delivery failures without logging the payload.
* During server rendering, `track()` is a no-op.

## Track only later page views

The first `PageView` is automatic. Call `track("PageView", ...)` only after a later client-side route change.

```typescript theme={null}
track("PageView", {
  sourceUrl: window.location.href,
  pageTitle: document.title,
});
```

<CardGroup cols={2}>
  <Card title="Event names" icon="list" href="/api-reference/events" />

  <Card title="Payload types" icon="brackets-curly" href="/api-reference/payload" />
</CardGroup>