Track configurator activity

Use plugin events to send supported product activity to a browser data layer. Keep analytics naming and destination configuration in plugin options.

Define the options

type AnalyticsOptions = {
  dataLayerName?: string
  eventPrefix?: string
}

Push selected events

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

export default definePlugin<AnalyticsOptions>({
  id: 'customer.analytics',
  version: '1.0.0',
  apiVersion: PLUGIN_API_VERSION,

  setup(api, configuredOptions) {
    const options = {
      dataLayerName: 'dataLayer',
      eventPrefix: 'icon_visualizer',
      ...configuredOptions,
    }

    const host = window as unknown as Record<string, unknown>
    const existingLayer = host[options.dataLayerName]
    const dataLayer: unknown[] = Array.isArray(existingLayer) ? existingLayer : []
    host[options.dataLayerName] = dataLayer

    api.events.on('wheel:viewed', (event) => {
      dataLayer.push({
        event: `${options.eventPrefix}_wheel_viewed`,
        source: event.data.source,
        wheelImageId: event.data.wheelImageId,
        partNumber: event.data.partNumber,
      })
    })

    api.events.on('rfq:submitted', (event) => {
      dataLayer.push({
        event: `${options.eventPrefix}_rfq_submitted`,
        success: event.data.success,
      })
    })
  },
})

Known event names infer their payload types from the SDK. Subscribe only to events needed by the analytics plan.

Configure and queue

queuePlugin(analyticsPlugin, {
  order: 40,
  required: false,
  options: {
    dataLayerName: 'YOUR_DATA_LAYER',
    eventPrefix: 'YOUR_EVENT_PREFIX',
  },
})

Data guidance

• Send stable identifiers and explicit public fields instead of entire event objects.
• Do not put customer contact details or credentials into analytics payloads.
• Keep analytics optional so a vendor failure cannot stop the configurator.
• Validate the final payload in the browser before enabling production collection.

If the standard built-in behavior is sufficient, configure the analytics built-in instead of maintaining custom code.