Skip to main content
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: 
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

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.
For custom theme switchers, use the programmatic integration guide: Sync widget theme with website

​
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.