> For the complete documentation index, see [llms.txt](https://docs.carpose.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carpose.de/events/01_introduction.md).

# Introduction

This section provides an overview of the JavaScript events emitted by the Carposé React application. These events serve as integration points for manual intervention, custom analytics, and behavioral tracking. **Carposé does not track or collect user behavior by default.** Instead, it leaves full control to the implementer to decide when and how such tracking should occur. Concretely, this means the app only dispatches plain DOM `CustomEvent`s — it never calls `dataLayer.push`, `gtag`, `fbq`, or any other analytics SDK itself.

The following pages detail all available event types, including their payloads and recommended use cases. These events can be used to build custom logging, analytics pipelines, or trigger external workflows based on user interaction within the Carposé app.

### Naming Grammar <a href="#naming-grammar" id="naming-grammar"></a>

Every public event name follows the same grammar:

```
carpose-<entity>-<feature>-<action>
```

* **entity** — one of `vehicle`, `offer`, `store`, `employee`, `ui`. This is **not** the UI surface the interaction happened on — it is whatever the event's `data` payload describes. For example, the wishlist, the vehicle comparison tray, the AI search assistant, and the budget calculator are all distinct UI surfaces, but each of them acts on vehicle data, so all of their events live under `carpose-vehicle-*` and all carry the same vehicle payload shape (see [Vehicle Search](/events/02_vehicle-search.md)). The surface itself is reported separately, in `detail.component`.
* **feature** — an optional grouping such as `contact`, `search`, `wishlist`, `comparison`, `budget`, `viewer`, `test-drive`, `purchase`, `configurator`. Some events (e.g. `carpose-vehicle-select`, `carpose-offer-select`, `carpose-store-select`) have no feature segment.
* **action** — what happened, e.g. `select`, `open`, `add`, `form-success`.

### The v2 Envelope <a href="#the-v2-envelope" id="the-v2-envelope"></a>

Every event is dispatched on `document.body` with `bubbles: true`, so a single listener attached anywhere in the ancestor chain (including directly on `document.body`) will catch it. The `CustomEvent.detail` object always has this shape:

```json
{
  "message": "Human-readable label, e.g. \"Vehicle select\"",
  "type": "vehicle | offer | store | employee | ui",
  "feature": "Optional grouping, e.g. \"contact\" — omitted when the event has none",
  "action": "What happened, e.g. \"select\" or \"form-success\"",
  "channel": "Optional contact/search channel, e.g. \"phone\", \"mail\", \"whatsapp\", \"form\", \"ai\" — omitted when not applicable",
  "component": "The mounted widget that rendered the interaction, e.g. \"vehicle-search-form\", \"vehicle-slider\"",
  "version": 2,
  "data": "Event-specific payload — stable per entity, see the catalogue pages"
}
```

Field reference:

| Field       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `message`   | Human-readable label for the event. Convenient for debug logging, not meant to be parsed.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `type`      | The entity — see Naming Grammar above.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `feature`   | Optional. The feature grouping segment of the event name, when the event has one.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `action`    | The action segment of the event name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `channel`   | Optional. Present on contact and some search events to indicate the channel used (`phone`, `mail`, `whatsapp`, `form`, `ai`). Note that `channel` alone does not always distinguish everything you might expect — see the callout on `carpose-vehicle-search-submit` in [Vehicle Search](/events/02_vehicle-search.md).                                                                                                                                                                                                        |
| `component` | The mounted widget instance that rendered the interaction (the value passed to `data-carpose-component` when the widget was embedded), e.g. `vehicle-search-form`, `vehicle-slider`, `offer-item`. Several widgets can share the same event name — e.g. a vehicle card can be rendered by the search form, a vehicle slider, or the vehicle detail page — so `component` is how you tell them apart. A few narrowly-scoped components (like the 360° exterior viewer) report their own name directly instead of an ancestor's. |
| `version`   | Always `2` for events documented on this page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `data`      | The event-specific payload. Its shape is stable per entity — every `vehicle` event carries the same vehicle fields, every `offer` event the same offer fields, and so on — see the catalogue pages for exact shapes.                                                                                                                                                                                                                                                                                                           |

### Internal Command Events — Do Not Track <a href="#internal-command-events" id="internal-command-events"></a>

A small number of events under the **`carpose-internal-*`** namespace exist purely as cross-component commands inside the Carposé app itself — for example, telling a search form to preset a vehicle type, or telling it that the AI assistant's state changed. They are dispatched on **`window`**, not `document.body`, do **not** use the v2 envelope described above, and their shape can change at any time without notice.

**Do not attach analytics or business logic to any `carpose-internal-*` event.** They are not part of the public event surface, are not listed in the catalogue pages, and are excluded from the breaking-change guarantees described on the [Deprecated Events](/events/08_deprecated-events.md) page.