Bridge events to the host page

A plugin can translate configurator activity into customer-owned CustomEvent values. This keeps the host integration small and avoids exposing the plugin API outside the plugin artifact.

Dispatch a focused payload

import { PLUGIN_API_VERSION, definePlugin } from '@iconfigurators/plugin-sdk'

export default definePlugin({
  id: 'customer.host-event-bridge',
  version: '1.0.0',
  apiVersion: PLUGIN_API_VERSION,

  setup(api) {
    api.events.on('wheel:selected', (event) => {
      const wheel = event.data.wheel as {
        wheelImageId?: string | number
        brandName?: string
        modelName?: string
      }

      window.dispatchEvent(
        new CustomEvent('customer:wheel-selected', {
          detail: {
            wheelImageId: wheel.wheelImageId ?? null,
            brandName: wheel.brandName ?? null,
            modelName: wheel.modelName ?? null,
            source: event.data.source,
          },
        }),
      )
    })
  },
})

Listen on the embedding website

<script>
  window.addEventListener('customer:wheel-selected', (event) => {
    console.log('Selected wheel', event.detail)
  })
</script>

Register the host listener before loading the plugin and embed when the first occurrence matters.

Design a stable host contract

• Use a customer-owned prefix for event names.
• Copy only the public fields the host needs.
• Treat the plugin event payload as read-only.
• Document nullable and optional values.
• Avoid forwarding entire product, RFQ, or diagnostic records.
• Never include credentials or private customer data.

For host code that needs to run after initialization rather than after product activity, use the iconfigurator.ready document event.