Campaigns API

Register a structured marketing prompt with api.campaigns.register(campaign). Registration returns an unsubscribe function.

type MarketingCampaign = {
  id: string
  enabled?: boolean
  placement?: 'modal'
  trigger?: MarketingCampaignTrigger
  triggers?: MarketingCampaignTrigger[]
  priority?: number
  delayMs?: number
  conditions?: MarketingCampaignConditions
  frequency?: MarketingCampaignFrequency
  creative: MarketingCampaignCreative
}

Trigger and placement

Supported triggers are:

• app:mounted
• app:ready
• route:changed
• landing:viewed
• wheels:loaded
• wheel:selected
• wheel:viewed
• rfq:opened
• search:navigation-opened
• search:vehicle-opened
• search:size-opened

Use either trigger for one value or triggers for several. The supported placement is modal. Higher priority values take precedence when several campaigns qualify.

Conditions

type MarketingCampaignConditions = {
  routes?: string[]
  excludeRoutes?: string[]
  pathIncludes?: string[]
}

Conditions narrow where an otherwise eligible trigger may display the campaign.

Frequency

type MarketingCampaignFrequency = {
  oncePerSession?: boolean
  maxPerSession?: number
  cooldownHours?: number
}

Creative

type MarketingCampaignCreative = {
  layout?: 'hero' | 'split' | 'compact'
  eyebrow?: string
  title: string
  body?: string
  badge?: string
  media?: {
    type: 'image'
    src: string
    alt: string
    aspectRatio?: string
  }
  accentColor?: string
  actions?: MarketingCampaignAction[]
}

An action requires a label and command. Supported commands include plugin action commands plus dismiss. Its optional variant is primary, secondary, or link.

Example

api.campaigns.register({
  id: 'wheel-package-offer',
  trigger: 'wheel:viewed',
  priority: 20,
  frequency: {
    oncePerSession: true,
  },
  creative: {
    layout: 'compact',
    eyebrow: 'Package offer',
    title: 'Complete the look',
    body: 'Ask about a mounted wheel and tire package.',
    actions: [
      {
        label: 'Shop by vehicle',
        command: 'openSearchByVehicle',
      },
      {
        label: 'Keep browsing',
        command: 'dismiss',
        variant: 'secondary',
      },
    ],
  },
})

Events

• campaign:shown reports campaign ID, plugin ID, trigger, and optional trigger data.
• campaign:action reports the selected action.
• campaign:dismissed reports the dismissal reason.

Use the marketing-campaigns built-in when campaign definitions should come entirely from account or host configuration.