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

# Track events

> Call thradTag("event", name, params) for any standard or custom event.

Once the [Tag is installed](https://docs.thrad.ai/advertisers/attribution/tag/install.md), call:

```js theme={null}
window.thradTag("event", "<event_name>", {
  // any properties you want attached to the event
});
```

The general event command accepts custom event names. Use the standard taxonomy for consistent reporting; OpenAI delivery also requires a matching configured event map. Purchase aliases use the validated purchase path described below.

## Standard events

The **category** column describes event data used for measurement. Purchases have validated order fields; supported leads and registrations use `customer_action` data and their own submission identities.

| Event | Category | Fires when… |
| - | - | - |
| `contents_viewed` | `contents` | A user views a product, listing, article, or other content unit. |
| `items_added` | `contents` | A user adds one or more items to a cart, bundle, or selection. |
| `checkout_started` | `contents` | A user starts checkout. |
| `order_created` | `contents` | A purchase is completed. |
| `lead_created` | `customer_action` | A user submits a lead form or requests contact. |
| `appointment_scheduled` | `customer_action` | A user books a meeting, demo, or consultation. |
| `registration_completed` | `customer_action` | A user finishes an account or event registration flow. |
| `trial_started` | `plan_enrollment` | A free trial starts. |
| `subscription_created` | `plan_enrollment` | A paid subscription starts. |
| `custom` | `custom` | Any user-defined event not covered above. |

## Examples

```js theme={null}
// Content view
window.thradTag("event", "contents_viewed", {
  content_id: "sku_123",
  content_type: "product"
});

// Cart add
window.thradTag("event", "items_added", {
  content_id: "sku_123",
  quantity: 2,
  value: 58.00,
  currency: "USD"
});

// Lead form submission
window.thradTag("event", "lead_created", {
  event_id: "lead:submission_123",
  form_id: "newsletter"
});

// Custom — anything you like
window.thradTag("event", "video_completed", {
  video_id: "promo-q3",
  duration_ms: 32000
});
```

## Leads and signups

Use a stable opaque identity from each completed submission, without customer
details. Reuse the same `event_id` when reporting that submission again; use a
new ID for a different submission. No `order_id`, value or currency is required.

```js theme={null}
window.thradTag("event", "registration_completed", {
  event_id: "registration:submission_456"
});
```

For OpenAI measurement, configure mappings to `lead_created` and
`registration_completed`. Existing names such as `lead` and `signup` require
matching configured mappings. The tag supplies `customer_action` event data.
Signed Thrad and OpenAI source context are retained when available. An organic
event with no supported attribution context is not submitted by this tag.

## Event properties

General events may carry additional properties. Supported measurement fields are normalized by the tag and collector; avoid assuming every property is forwarded unchanged to a measurement provider.

That said, using consistent property names across your site makes the data much easier to slice in reporting. Common conventions you'll see in the examples above (`content_id`, `quantity`, `value`, `currency`, `form_id`, …) are conventions, not requirements.

For a completed purchase, use [Track purchases](https://docs.thrad.ai/advertisers/attribution/tag/conversions.md). The `conversion` command and purchase aliases such as `order_created`, `purchase` and `checkout_completed` share the canonical purchase path: final `order_id`, nonnegative `value` and three-letter `currency` are required. A lead or signup must not be sent as a purchase just to obtain attribution.


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