Register a plugin

Registration timing determines which lifecycle moments a plugin can observe.

Register before startup

Use queuePlugin() in a classic browser artifact loaded before embed.cfm:

import { queuePlugin } from '@iconfigurators/plugin-sdk'
import plugin from './plugin'

queuePlugin(plugin, {
  order: 50,
  required: false,
  options: {
    dealerId: 'DEALER_ID',
  },
})

Preboot registration is required for settings:filter and is appropriate when a plugin must see early lifecycle events.

Register after startup

Use late registration when future events, active outlets, and commands are sufficient:

const hostApi = await window.iConfigurator.ready()

const registration = await hostApi.registerPlugin(plugin, {
  options: {
    dealerId: 'DEALER_ID',
  },
})

console.log(registration.status)

Late registration does not replay app:settings-loaded, app:before-mount, app:mounted, or app:ready. A late settings:filter callback cannot rebuild startup settings.

Order and uniqueness

Lower order values set up first. Active IDs must be unique across preboot, built-in, and late plugins. Do not rely on discovery order to replace a duplicate ID.

Use required: false for analytics, promotions, navigation changes, and other optional additions. Only mark a plugin required when the base configurator cannot safely operate without it.

Unregister and clean up

window.iConfigurator.unregisterPlugin('customer.dealer-recommendation')

The plugin system removes resources registered through its public API. The plugin must still clean up timers, document listeners, observers, sockets, and external library instances that it created directly. Return that cleanup from setup():

setup() {
  const controller = new AbortController()
  document.addEventListener('customer-event', handleCustomerEvent, {
    signal: controller.signal,
  })

  return () => controller.abort()
}