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

# Tracking events

> Developer reference for Remapdb widget events used in custom analytics and custom website behavior.

This page is for advanced integrations.

If you only need standard widget setup, you do not need to implement these events manually.

## How event communication works

Remapdb widget communicates with your website using events.

Event name format:

* `rdb-eventName`

Why this matters:

* It helps prevent cross-talk when multiple widgets exist on one page.
* Your listener should always filter by event name and origin.

## Events emitted from the widget

### `rdb-queryKey`

The widget sends the query key name it uses (default is usually `catalog`).

Important detail:

* Use this key when building custom URL rules on your website side.

### `rdb-seoConfig`

The widget sends SEO configuration flags and templates.

Important detail:

* This allows parent-page SEO updates (title, description, OG, JSON-LD) to stay aligned with widget settings.

### `rdb-vehicleMeta`

The widget sends current selected vehicle metadata and gains.

Important detail:

* This is the main event for analytics integrations.

Typical payload fields include:

* Vehicle type, brand, model, generation, engine.
* Vehicle name and language.
* Engine fuel type.
* Gains for different stages.
* Language
* Stages
* URL path.

Listener Example:

```js theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://app.remapdb.com") return;

  const evt = event?.data?.event || "";
  if (!evt.endsWith("-vehicleMeta")) return;

  const meta = event?.data?.meta;
  if (!meta) return;

  window.dataLayer?.push({
    event: "remapdb_vehicle_selected",
    vehicle: meta.vehicleName,
    type: meta.type,
    brand: meta.brand,
    model: meta.model,
    generation: meta.generation,
    image: meta.image,
    engine: meta.engine,
    fuelType: meta.fuelType,
    gains: meta?.gains,
    language: meta.language,
    stages: meta?.stages,
    urlPath: meta.urlPath,
  });
});
```

### `rdb-updateUrlPath`

The widget asks your website to update the browser URL with the current vehicle path.

Important detail:

* Applied only when link sharing is enabled.

### `rdb-requestCurrentURL`

The widget asks for the current full page URL.

### `rdb-switchLanguage`

The widget asks your website to reload iframe with a selected language.

Important detail:

* Applied only when link sharing is enabled.

## Programmatic theme control

If your website has a light/dark switch, you can notify the widget by firing this event from your website page:

### `rdb-theme`

```js theme={null}
window.dispatchEvent(new CustomEvent("rdb-theme", {
  detail: { theme: "dark" } // light | dark | auto
}));
```

Important detail:

* This is consumed by widget runtime. It is not emitted by the widget.
* Use it when your website changes theme via custom theme switcher.

<Info>
  For custom theme switchers, use the programmatic integration guide:
  [Sync widget theme with website](/widget/branding/theme-sync-with-website)
</Info>

## Implementation safeguards

* Always verify `event.origin`.
* Filter only Remapdb namespaced events.
* Ignore events without expected payload fields.
* Add tracking listeners in your own website code or tag manager.
* You do not need to edit Remapdb widget files.

## Troubleshooting

* Confirm the widget is loaded and interactive first.
* Open browser developer tools and inspect `message` events.
* Confirm your origin check matches your real app domain.
* Confirm your listener loads after widget initialization.

## Related actions

* [Tracking](/widget/tracking)
* [Sync widget theme with website](/widget/branding/theme-sync-with-website)
* [Code installation](/widget/installation/code-installation)
* [WordPress plugin installation](/widget/installation/wordpress-plugin-installation)