Events reference

Every callback receives { type, timestamp, data }. Known names infer their payload through the SDK.

Application and route events

Event	Payload summary
app:settings-loaded	Resolved public options and configured language names.
app:before-mount	Public configurator snapshot before the interface mounts.
app:mounted	Public snapshot immediately after the interface mounts.
app:ready	Public snapshot after initial plugin lifecycle completes.
route:changed	Serializable to and from routes.
theme:changed	Current light or dark theme.
language:changed	Current language code.

Landing and search events

Event	Payload summary
landing:viewed	Landing-view context.
landing:featured-brands-loaded	Featured brand records.
landing:featured-wheels-loaded	Featured wheel records.
landing:data-load-failed	Public error message.
landing:section-visible	Section ID, plugin ID, and placement.
landing:section-item-selected	Section details, item ID, and action.
landing:section-action-failed	Selection details and failure message.
search:navigation-opened	Optional source.
search:vehicle-opened	Optional source.
search:vehicle-submitted	Submitted public search data.
search:size-opened	Optional source.
search:size-submitted	Submitted public search data.

Catalog and product events

Event	Payload summary
brands:viewed	Brand-directory source.
brands:loaded	Filtered brands plus original and result counts.
brand:selected	Brand identity, record, source, and destination when available.
wheels:loaded	Source, filters, result counts, and optional brand or vehicle.
wheel:selected	Wheel, source, resolved destination, and available context.
wheel:viewed	Wheel image ID and available detail data.
wheel:spec-size-selected	Selected model-level size information.
wheel:spec-selected	Selected wheel, vehicle, and exact spec when available.

RFQ, campaign, modal, and error events

Event	Payload summary
rfq:opened	Wheel, vehicle, tire-selection state, and tire inclusion.
rfq:dealer-selected	Available public identifiers for the selected dealer.
rfq:submitted	Submitted payload, response, success state, wheel, and vehicle.
campaign:shown	Campaign ID, plugin ID, trigger, and optional data.
campaign:dismissed	Campaign ID, plugin ID, and dismissal reason.
campaign:action	Campaign ID, plugin ID, and selected action.
modal:opened	Modal ID, plugin ID, title, and size.
modal:closed	Modal identity and close reason.
plugin:error	Plugin ID, plugin lifecycle phase, and public error message.

Custom event names remain type-compatible when a plugin supplies an explicit payload type, but the visualizer emits only documented product names.

Event envelope

Every subscription receives the event name, a millisecond timestamp, and its typed payload:

type ConfiguratorEvent<T, TName extends string> = {
  type: TName
  timestamp: number
  data: T
}

Lifecycle payloads

app:settings-loaded contains approved public options and configured language names:

type AppSettingsLoadedPayload = {
  options: PluginSettingsOptions
  languages: Array<{ langName: string }>
}

app:before-mount, app:mounted, and app:ready carry a ConfiguratorSnapshot.

Route and preference payloads

type RouteChangedPayload = {
  to: SerializableRoute
  from: SerializableRoute
}

type SerializableRoute = {
  name: string | null | undefined
  path: string
  fullPath: string
  query: Record<string, unknown>
  params: Record<string, unknown>
}

type ThemeChangedPayload = { theme: 'light' | 'dark' }
type LanguageChangedPayload = { lang: string }

Landing payloads

Event	Fields
landing:viewed	Public landing context when available.
landing:featured-brands-loaded	brands: PluginBrandRecord[]
landing:featured-wheels-loaded	wheels: PluginWheelRecord[]
landing:data-load-failed	message: string
landing:section-visible	sectionId, pluginId, placement
landing:section-item-selected	Section fields plus itemId and action
landing:section-action-failed	Selection fields plus public message

Catalog payloads

type BrandsLoadedPayload = {
  source: 'brands'
  brands: PluginBrandRecord[]
  originalCount: number
  resultCount: number
}

type BrandSelectedPayload = {
  source?: string
  brandId: string | number
  brand?: PluginBrandRecord
  destination?: PluginRouteLocation
}

type WheelsLoadedPayload = {
  source: string
  filters: Record<string, unknown>
  resultCount: number
  recordCount: number
  brand?: PluginBrandRecord | null
  vehicle?: unknown
}

Wheel events contain the following supported fields:

Event	Fields
wheel:selected	source, wheel, and optional wheelCard, destination, brand, vehicle, and filters
wheel:viewed	source, wheelImageId, and optional partNumber, details, specs, and assets
wheel:spec-size-selected	source and optional wheelImageId, details, and pill
wheel:spec-selected	source and optional wheel, vehicle, and spec

Fields typed as unknown must be narrowed before use. Do not assume that optional context is available on every product surface.

RFQ payloads

type RFQOpenedPayload = {
  wheel: unknown
  vehicle?: unknown
  initialIsSelecting: '' | 'TIRES'
  includesTires: boolean
}

type RFQDealerSelectedPayload = {
  dealerId?: string | number
  dealerCode?: string | number
}

type RFQSubmittedPayload = {
  payload: unknown
  rfq: unknown
  response: unknown
  success: boolean
  wheel: unknown
  vehicle?: unknown
}

Treat RFQ records as sensitive customer interaction data. Forward only explicitly required fields to customer-owned systems.

Campaign and modal payloads are documented with the Campaigns API and Plugin modals API. plugin:error contains pluginId, phase, and a public message.