Automotive Event Spec

This page defines all standard automotive events for Datafly Signal — covering OEM marketing sites, dealer groups, online vehicle marketplaces, and aftersales/service portals. Implement these events to enable accurate server-side delivery to advertising and analytics platforms across the full funnel: discover, configure, qualify, convert, and retain.

💡

These event names come from Signal’s live automotive blueprints. The cross-vertical events (page, search, view_item_list, sign_up, login, generate_lead) reuse GA4’s recommended names where an e-commerce equivalent exists; automotive-specific actions use snake_case noun-then-action names (vehicle_viewed, test_drive_booked, trade_in_valued). Use these names verbatim — Signal’s blueprints map them to each vendor’s native event in the Vendor Mapping table, so renaming them breaks delivery.

All events are sent via datafly.track(). Properties are passed as a flat object in the second argument. Vehicles are identified by item_id (your internal stock ID or VIN-derived ID). Monetary amounts are numbers with a separate currency property using ISO 4217 codes.

⚠️

Never pass raw PII (email, phone, or name) into track() properties. Signal collects and hashes identifiers automatically via datafly.identify() and collected vendor_ids.

Browsing Events

`vehicle_searched`

Fired when a user submits a search against the vehicle inventory.

datafly.track('vehicle_searched', {
  search_term: 'phev suv under 60k',
  make: 'BMW',
  body_type: 'suv',
  condition: 'used',
  fuel_type: 'phev',
  transmission: 'automatic',
  min_price: 30000,
  max_price: 60000,
  min_year: 2021,
  max_mileage: 40000,
  postcode: 'SW1A',
  radius_miles: 50,
  results_count: 42
})

Property	Type	Required	Description
`search_term`	string	Optional	Free-text query if submitted
`make`	string	Optional	Manufacturer filter (e.g. `BMW`)
`model`	string	Optional	Model filter (e.g. `3 Series`)
`body_type`	string	Optional	`saloon`, `suv`, `hatchback`, `estate`, `coupe`, etc.
`condition`	string	Optional	`new`, `used`, `certified_pre_owned`
`fuel_type`	string	Optional	`petrol`, `diesel`, `hybrid`, `phev`, `bev`
`transmission`	string	Optional	`manual`, `automatic`
`min_price` / `max_price`	number	Optional	Price range filters
`min_year` / `max_year`	number	Optional	Year range filters
`max_mileage`	number	Optional	Mileage cap (used vehicles)
`postcode`	string	Optional	Buyer’s outward postcode for proximity search
`radius_miles`	number	Optional	Search radius from postcode
`results_count`	number	Optional	Number of results returned

`search`

Fired for a generic site search that is not scoped to vehicle inventory (e.g. searching help content, dealer locations, or news). For inventory searches, use vehicle_searched instead.

datafly.track('search', {
  search_term: 'nearest bmw dealer'
})

Property	Type	Required	Description
`search_term`	string	Required	The search term entered by the user

`view_item_list`

Fired when a user views a search results grid, inventory listing, or model range page.

datafly.track('view_item_list', {
  item_list_id: 'used-bmw-suv',
  item_list_name: 'Used BMW SUVs',
  items: [
    { item_id: 'STK-7421', item_name: 'BMW X3 xDrive30e', item_brand: 'BMW', item_category: 'SUV', price: 49995, index: 0 },
    { item_id: 'STK-7422', item_name: 'BMW X5 xDrive45e', item_brand: 'BMW', item_category: 'SUV', price: 64995, index: 1 }
  ]
})

Property	Type	Required	Description
`item_list_id`	string	Optional	Machine-readable identifier for the listing or collection
`item_list_name`	string	Optional	Human-readable name of the listing being browsed
`items`	array	Optional	Array of vehicle objects displayed (see Items Array Schema)

`vehicle_viewed`

Fired when a user opens a vehicle detail page (VDP). The vehicle-detail view is always vehicle_viewed, not view_item — Signal maps it to GA4 view_item / Meta ViewContent for you.

datafly.track('vehicle_viewed', {
  currency: 'GBP',
  value: 49995,
  items: [
    {
      item_id: 'STK-7421',
      item_name: 'BMW X3 xDrive30e',
      item_brand: 'BMW',
      item_category: 'SUV',
      item_variant: 'M Sport',
      condition: 'new',
      fuel_type: 'phev',
      year: 2024,
      mileage: 10,
      price: 49995,
      currency: 'GBP',
      dealer_id: 'D-1138'
    }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code (e.g. `GBP`, `USD`)
`value`	number	Optional	List or sticker price of the vehicle
`items`	array	Optional	Array containing the viewed vehicle (see Items Array Schema)

`view_promotion`

Fired when a promotional offer or finance banner is visible to the user.

datafly.track('view_promotion', {
  promotion_id: 'PCP-SUMMER24',
  promotion_name: '0% APR Summer Event',
  creative_name: 'summer-apr-hero.jpg',
  creative_slot: 'homepage-hero'
})

Property	Type	Required	Description
`promotion_id`	string	Optional	Identifier for the promotion
`promotion_name`	string	Optional	Human-readable name of the promotion
`creative_name`	string	Optional	Name or URL of the creative asset shown
`creative_slot`	string	Optional	Slot or placement where the promotion appeared

`select_promotion`

Fired when a user clicks a promotional offer or finance banner.

datafly.track('select_promotion', {
  promotion_id: 'PCP-SUMMER24',
  promotion_name: '0% APR Summer Event',
  creative_name: 'summer-apr-hero.jpg',
  creative_slot: 'homepage-hero'
})

Accepts the same properties as view_promotion.

Engagement Events

`vehicle_saved`

Fired when a user favourites or saves a vehicle to return to later.

datafly.track('vehicle_saved', {
  currency: 'GBP',
  value: 49995,
  items: [
    { item_id: 'STK-7421', item_name: 'BMW X3 xDrive30e', item_brand: 'BMW', item_category: 'SUV', price: 49995 }
  ]
})

Property	Type	Required	Description
`currency`	string	Optional	ISO 4217 currency code
`value`	number	Optional	Monetary value of the saved vehicle
`items`	array	Optional	Array containing the saved vehicle (see Items Array Schema)

`vehicle_compared`

Fired when a user adds a vehicle to a side-by-side comparison.

datafly.track('vehicle_compared', {
  compared_count: 3,
  items: [
    { item_id: 'STK-7421', item_name: 'BMW X3 xDrive30e', item_brand: 'BMW' },
    { item_id: 'STK-7422', item_name: 'BMW X5 xDrive45e', item_brand: 'BMW' },
    { item_id: 'STK-9001', item_name: 'Audi Q5 TFSI e', item_brand: 'Audi' }
  ]
})

Property	Type	Required	Description
`compared_count`	number	Optional	Number of vehicles currently in the comparison
`items`	array	Optional	Array of vehicles in the comparison (see Items Array Schema)

`brochure_downloaded`

Fired when a user downloads a spec sheet or brochure (PDF).

datafly.track('brochure_downloaded', {
  brochure_id: 'BR-X3-2024',
  item_id: 'STK-7421',
  make: 'BMW',
  model: 'X3',
  language: 'en'
})

Property	Type	Required	Description
`brochure_id`	string	Optional	Internal ID for the brochure asset
`item_id`	string	Optional	Vehicle the brochure is for, if scoped
`make`	string	Optional	Manufacturer
`model`	string	Optional	Model
`language`	string	Optional	Brochure language (ISO 639-1)

`configure_vehicle`

Fired when a user builds or customises a vehicle in a configurator (selecting trim, options, colour). A strong intent signal for new-vehicle marketing.

datafly.track('configure_vehicle', {
  make: 'BMW',
  model: 'X3',
  trim: 'M Sport',
  exterior_colour: 'Phytonic Blue',
  configured_price: 54320,
  currency: 'GBP',
  options: ['panoramic_roof', 'tech_pack', 'tow_bar']
})

Property	Type	Required	Description
`make`	string	Required	Manufacturer of the configured vehicle
`model`	string	Optional	Model being configured
`trim`	string	Optional	Trim or variant selected
`exterior_colour`	string	Optional	Selected exterior colour/paint
`configured_price`	number	Optional	Total price of the build as configured
`currency`	string	Optional	ISO 4217 currency code
`options`	array	Optional	List of selected option/pack identifiers

Qualification Events

`finance_quote_requested`

Fired when a user runs the finance/lease calculator and a monthly payment is shown.

datafly.track('finance_quote_requested', {
  item_id: 'STK-7421',
  finance_type: 'pcp',
  term_months: 36,
  deposit: 5000,
  annual_mileage: 10000,
  monthly_payment: 489,
  apr: 6.9,
  currency: 'GBP'
})

Property	Type	Required	Description
`item_id`	string	Optional	Vehicle the calculation is for
`finance_type`	string	Optional	`pcp`, `hp`, `lease`, `cash`
`term_months`	number	Optional	Term length in months
`deposit`	number	Optional	Initial deposit amount
`annual_mileage`	number	Optional	Agreed annual mileage
`monthly_payment`	number	Optional	Calculated monthly payment shown
`apr`	number	Optional	Representative APR shown
`currency`	string	Optional	ISO 4217 currency code

`trade_in_valued`

Fired when a user completes a part-exchange / trade-in valuation.

datafly.track('trade_in_valued', {
  current_vehicle_make: 'Ford',
  current_vehicle_model: 'Focus',
  current_vehicle_year: 2018,
  current_vehicle_mileage: 42000,
  valuation_amount: 8750,
  currency: 'GBP'
})

Property	Type	Required	Description
`current_vehicle_make`	string	Optional	Make of the trade-in vehicle
`current_vehicle_model`	string	Optional	Model of the trade-in vehicle
`current_vehicle_year`	number	Optional	Year of the trade-in vehicle
`current_vehicle_mileage`	number	Optional	Odometer reading of the trade-in
`valuation_amount`	number	Optional	Calculated trade-in value
`currency`	string	Optional	ISO 4217 currency code

Lead & Conversion Events

`generate_lead`

Fired when a user submits a high-intent lead form — a “request a quote”, a callback request, or any enquiry that creates a qualified lead. This is a primary automotive conversion event for ad platforms.

datafly.track('generate_lead', {
  lead_type: 'callback',
  item_id: 'STK-7421',
  dealer_id: 'D-1138',
  finance_type: 'pcp',
  value: 489,
  currency: 'GBP'
})

Property	Type	Required	Description
`lead_type`	string	Optional	`finance_quote`, `callback`, `reserve`, `enquiry`
`item_id`	string	Optional	Vehicle the lead is scoped to, if any
`dealer_id`	string	Optional	Dealer the lead is routed to
`finance_type`	string	Optional	`pcp`, `hp`, `lease`, `cash` (when finance-related)
`value`	number	Optional	Estimated lead value (e.g. monthly payment or vehicle price)
`currency`	string	Optional	ISO 4217 currency code

⚠️

Do not include the customer’s email, phone, or name in generate_lead properties. Signal hashes identifiers server-side from the collected identity and datafly.identify() traits.

`dealer_contacted`

Fired when a user submits an enquiry or contact form to a dealer.

datafly.track('dealer_contacted', {
  dealer_id: 'D-1138',
  item_id: 'STK-7421',
  enquiry_type: 'availability',
  channel: 'form'
})

Property	Type	Required	Description
`dealer_id`	string	Required	The dealer being contacted
`item_id`	string	Optional	Specific vehicle, if the enquiry is scoped
`enquiry_type`	string	Optional	`price`, `availability`, `finance`, `general`
`channel`	string	Optional	`form`, `whatsapp`, `live_chat`, `callback`, `phone`

`test_drive_booked`

Fired when a user books a test drive — a high-value lead event.

datafly.track('test_drive_booked', {
  item_id: 'STK-7421',
  dealer_id: 'D-1138',
  appointment_at: '2026-05-12T10:30:00Z',
  make: 'BMW',
  model: 'X3',
  value: 49995,
  currency: 'GBP'
})

Property	Type	Required	Description
`item_id`	string	Required	Vehicle being test-driven
`dealer_id`	string	Optional	Dealer hosting the test drive
`appointment_at`	string	Optional	ISO 8601 timestamp of the booked slot
`make`	string	Optional	Manufacturer
`model`	string	Optional	Model
`value`	number	Optional	List price of the vehicle
`currency`	string	Optional	ISO 4217 currency code

`vehicle_reserved`

Fired when a user places a refundable deposit to reserve a vehicle online.

datafly.track('vehicle_reserved', {
  item_id: 'STK-7421',
  dealer_id: 'D-1138',
  deposit: 99,
  value: 49995,
  currency: 'GBP'
})

Property	Type	Required	Description
`item_id`	string	Required	Vehicle being reserved
`dealer_id`	string	Optional	Dealer holding the reservation
`deposit`	number	Optional	Reservation deposit amount taken
`value`	number	Optional	List price of the reserved vehicle
`currency`	string	Optional	ISO 4217 currency code

`purchase`

Fired when a vehicle order is completed online (or recorded as sold). This is the primary revenue conversion — ensure it fires reliably.

datafly.track('purchase', {
  transaction_id: 'ORD-10042',
  value: 49995,
  currency: 'GBP',
  finance_type: 'pcp',
  dealer_id: 'D-1138',
  affiliation: 'BMW Park Lane',
  items: [
    {
      item_id: 'STK-7421',
      item_name: 'BMW X3 xDrive30e',
      item_brand: 'BMW',
      item_category: 'SUV',
      item_variant: 'M Sport',
      price: 49995,
      quantity: 1,
      currency: 'GBP'
    }
  ]
})

Property	Type	Required	Description
`transaction_id`	string	Required	Unique order identifier — used for deduplication
`value`	number	Optional	Total order value
`currency`	string	Optional	ISO 4217 currency code
`finance_type`	string	Optional	`pcp`, `hp`, `lease`, `cash`
`dealer_id`	string	Optional	Dealer that fulfilled the order
`affiliation`	string	Optional	Store or dealer that generated the order
`items`	array	Optional	Vehicle(s) purchased (see Items Array Schema)

⚠️

Always send transaction_id on purchase events for deduplication. Platforms like Meta CAPI and GA4 use the transaction ID to prevent double-counting alongside browser-side events.

Aftersales Events

`service_appointment_booked`

Fired when an existing customer books a service, MOT, or repair appointment.

datafly.track('service_appointment_booked', {
  dealer_id: 'D-1138',
  item_id: 'WBA-VIN-XYZ',
  service_type: 'mot',
  appointment_at: '2026-06-01T09:00:00Z',
  estimated_cost: 180,
  currency: 'GBP'
})

Property	Type	Required	Description
`dealer_id`	string	Optional	Dealer where the service is booked
`item_id`	string	Optional	The customer’s own vehicle (VIN or internal ID)
`service_type`	string	Optional	`routine`, `mot`, `recall`, `repair`
`appointment_at`	string	Optional	ISO 8601 timestamp of the booked slot
`estimated_cost`	number	Optional	Quoted cost
`currency`	string	Optional	ISO 4217 currency code

Account Events

`sign_up`

Fired when a user completes account registration (e.g. for a saved-search or “My Garage” account).

datafly.track('sign_up', {
  method: 'email'
})

Property	Type	Required	Description
`method`	string	Optional	Registration method (e.g. `email`, `google`, `apple`)

`login`

Fired when a user signs in to their account.

datafly.track('login', {
  method: 'email'
})

Property	Type	Required	Description
`method`	string	Optional	Login method (e.g. `email`, `google`, `apple`)

Items Array Schema

💡

Several events accept an items array, where each entry is a vehicle. Each object can include the following properties. The items[] array uses GA4-style field names. Signal’s server-side blueprints automatically transform these to vendor-specific formats (e.g., Meta’s contents[] with id/title fields).

Property	Type	Description
`item_id`	string	Internal stock ID or VIN-derived listing ID
`item_name`	string	Vehicle display name (e.g. `BMW X3 xDrive30e`)
`item_brand`	string	Manufacturer / make
`item_category`	string	Body type or category (e.g. `SUV`, `Saloon`)
`item_variant`	string	Trim or variant (e.g. `M Sport`)
`condition`	string	`new`, `used`, `certified_pre_owned`
`fuel_type`	string	`petrol`, `diesel`, `hybrid`, `phev`, `bev`
`year`	number	Model year
`mileage`	number	Odometer reading (used vehicles)
`price`	number	List or sticker price
`quantity`	number	Number of units (typically `1` for vehicles)
`index`	number	Position in list (0-indexed, relevant in list/search contexts)
`currency`	string	ISO 4217 currency code
`dealer_id`	string	ID of the dealership listing the vehicle
`item_list_id`	string	Identifier of the list the vehicle was shown in
`item_list_name`	string	Name of the list the vehicle was shown in

Common Context

All automotive events benefit from these properties on every event (set via datafly.identify() or page-level config):

Property	Type	Description
`customer_id`	string	Stable internal customer ID once identified
`dealer_group_id`	string	The franchise/group running the site
`region`	string	Sales region or country
`currency`	string	Default currency for the site

For platform identifiers (Meta, Google Ads, etc.), Signal handles those automatically via collected vendor_ids — you don’t need to send them on every event.

Vendor Mapping

The table below shows how Datafly Signal maps automotive events to the native event names expected by each vendor’s server-side API. Signal uses these snake_case event names as its canonical format, and blueprints handle the transformation to vendor-specific payloads.

Signal Event	GA4	Meta CAPI	TikTok Events API
`vehicle_searched`	`search`	`Search`	`Search`
`search`	`search`	`Search`	`Search`
`view_item_list`	`view_item_list`	`ViewContent`	`ViewContent`
`vehicle_viewed`	`view_item`	`ViewContent`	`ViewContent`
`view_promotion`	`view_promotion`	(custom)	(custom)
`select_promotion`	`select_promotion`	(custom)	(custom)
`vehicle_saved`	`add_to_wishlist`	`AddToWishlist`	`AddToWishlist`
`vehicle_compared`	(custom)	(custom)	(custom)
`brochure_downloaded`	(custom)	(custom)	`Download`
`configure_vehicle`	(custom)	`CustomizeProduct`	(custom)
`finance_quote_requested`	`generate_lead`	`Lead`	`SubmitForm`
`trade_in_valued`	(custom)	(custom)	(custom)
`generate_lead`	`generate_lead`	`Lead`	`SubmitForm`
`dealer_contacted`	`generate_lead`	`Contact`	`Contact`
`test_drive_booked`	`generate_lead`	`Schedule`	(custom)
`vehicle_reserved`	`add_to_cart`	`InitiateCheckout`	`InitiateCheckout`
`purchase`	`purchase`	`Purchase`	`CompletePayment`
`service_appointment_booked`	`generate_lead`	`Schedule`	(custom)
`sign_up`	`sign_up`	`CompleteRegistration`	`CompleteRegistration`
`login`	`login`	(custom)	(custom)

Travel & Hospitality Gaming