Plugin lifecycle

Registration timing determines which lifecycle callbacks and startup-only hooks a plugin can use.

Preboot sequence

For a plugin loaded before embed.cfm, the sequence is:

1. The browser artifact queues the plugin and its setup options.
2. Icon Visualizer discovers queued and configured plugins.
3. Initial plugins run setup() in ascending order.
4. Startup-only settings filters are applied.
5. app:settings-loaded is emitted with approved public settings.
6. app:before-mount is emitted.
7. Each applicable plugin runs beforeMount().
8. The configurator interface mounts.
9. app:mounted is emitted, followed by each applicable plugin's mounted() callback.
10. app:ready and the host-page readiness signal are emitted.

Use setup() for event, hook, command, campaign, and UI registration. Use lifecycle callbacks only when the plugin must distinguish a particular startup phase.

Plugin definition

export default definePlugin({
  id: 'customer.lifecycle-example',
  version: '1.0.0',
  apiVersion: PLUGIN_API_VERSION,

  setup(api) {
    // Register supported capabilities.
    return () => {
      // Dispose resources created directly by the plugin.
    }
  },

  beforeMount(api) {
    // Optional pre-interface work.
  },

  mounted(api) {
    // Optional work after the interface mounts.
  },
})

Late registration

A plugin registered through window.iConfigurator.registerPlugin() runs setup() immediately. It receives future events and currently available UI outlets, but startup events and lifecycle callbacks are not replayed.

Late plugins cannot use settings:filter for the current page load.

Ordering

Lower order values set up first. Hooks execute in plugin registration order, so each filter receives the previous plugin's valid result. Active plugin IDs must be unique regardless of source.

Do not use ordering to replace or override a duplicate plugin ID.

Failure behavior

An optional plugin failure records a failed registration and a public diagnostic error while the base configurator continues. A required plugin failure can stop successful startup.

Use required: false for analytics, promotions, navigation changes, and other enhancements that are not essential to the base shopping experience.

Disposal

Unregistration removes resources registered through the plugin API and invokes cleanup returned by setup(). A plugin must directly clean up anything it created outside that API, including:

• Document and window listeners
• Timers and observers
• Network subscriptions or sockets
• Plugin-owned renderer instances
• References to host or outlet elements

After complete disposal, the same plugin ID can be registered again.