Implementation
Events
ecViewecUserecProductecBasketItemecBasketItemActionecBasketItemTransactionecBasketTransactionSummaryecBasketSummary

Qubit event reference

This section documents the full specification of Qubit's QProtocol events.

On the left, you can filter by your site's vertical, and also choose to only show fields that are recommended for the particular products you are intending to use.

Use the Optional tickbox to show those events that we recommend adding in a more advaned QProtocol implementation.

Don't forget that we have a number of vertical-specific setup guides, which you can find in our Setup section, along with guides on mobile set up and CMS integrations.

For more information on how to setup Qubit's UV library for emitting events, you can refer to our setup documentation.

ecView

The ecView event reports a page view and is a special event because it is required by smartserve.js for data collection and processing. It is therefore essential that every page emits an ecView event and that it is emitted before any other event.

DANGER: Any events emitted before the first ecView event are considered invalid. Web and mobile applications emit view events whenever a view is rendered.

INFO: For Product Insights, type must be category. See the Merchandising Hub setup guide for more information.

Fields
  • typestring

    The type of view. Can be one of home, category, search, product, basket, checkout, confirmation, help, contact, registration, content, account, or other. Custom names can be used for unique page types that are not covered by this specification. All types must be lowercase

  • subtypesstring[]
    An unordered list of subtypes to describe the view
  • languagestring
    The language used in this view. Must be an IETF language code
  • countrystring
    The selected country for the view. Must be an ISO 3166-1 alpha-2 code
  • currencystring
    The ISO 4217 currency code for the user, e.g. GBP, USD
uv.emit('ecView', {
  type: 'category',
  subtypes: [
    'Womens',
    'Dresses',
    'Cocktail Dresses'
  ],
  language: 'en-us',
  country: 'US',
  currency: 'USD'
})

ecUser

The ecUser event is emitted once per view and reports visitor metadata. The event should be emitted on every page as long as there is data available for the user.

For many websites, the event will be present and well populated when the visitor logs on. Websites with a newsletter subscription form that the visitor has previously submitted, might be able to populate the name and email address for the visitor using the data collected on form submission.

WARNING: It is acceptable to emit hashed user Ids but be aware that to ingest data for use in Qubit's platform, the user Ids in the provided dataset must be hashed in the same way.

Fields
uv.emit('ecUser', {
  user: {
    id: '2861102bace6e6620948564f0ce0a7cd',
    firstName: 'John',
    lastName: 'Smith',
    username: 'JohnSmith',
    email: 'john@johnsmith.com'
  }
})

ecProduct

Product events report a product loaded on a page. This could be, for example, a main product, a linked product on a product detail page, a product in a listing page, or search page.

WARNING: This event is not used for Recommendations reporting. Refer to Reporting On Recommendations Experiences for more information.

The eventType field differentiates between the different scenarios and can be:

  • detail
  • linked_product

INFO: For Product Insights, eventType must be detail. See the Merchandising Hub setup guide for more information.

Fields
  • Id to identify a product, normally covering all of its size, color, pattern, and material variants
  • Unique product identifier to distinguish each product from all of the other size, color, pattern, material, age, group, gender variants
  • The product’s name, which should match the name shown on the product page
  • An accurate description of the product, which should match the description on the product page
  • A list of one or more product categories this product belongs to. Each category is a full path of a category where each level is separated by >

  • The price that the product is currently being sold at, after discounts
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The price of the product before discounts, promotions
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The fully qualified URL that the product is shown on
  • An array of fully qualified image URLs for the product. The main image you want to use to display the product must be the first element in the array
  • The number of items left in stock for the product. Should only be populated when the product is in stock and the exact number is known. Should be 0 if the product is out of stock. Where different product variants have different stock levels, use the maximum stock level
  • The product manufacturer, recommended when a product inventory includes multiple brands
  • The color of the product
  • The size of the product, e.g. 12, M, XL, 14
  • eventTypestring
    The type of product event, e.g. 'listing', 'detail', or 'linked_product'
uv.emit('ecProduct', {
  product: {
    productId: 'DRESS101',
    sku: 'DRESS101-12',
    name: 'Red Cocktail Dress',
    description: 'This red cocktail dress is perfect for any occasion',
    categories: [
      'Clothing > Sweaters > Short Sleeve Sweaters',
      'New Arrivals > Clothing'
    ],
    price: {
      value: 9.99,
      currency: 'USD'
    },
    originalPrice: {
      value: 9.99,
      currency: 'USD'
    },
    url: 'http://www.fashionunion.com/dresses/red-cocktail-dress.html',
    images: [
      'http://www.fashionunion.com/dresses/red-cocktail-dress-1.jpg',
      'http://www.fashionunion.com/dresses/red-cocktail-dress-2.jpg'
    ],
    stock: 20,
    manufacturer: 'Dress Inc',
    color: 'Red',
    size: '12'
  },
  eventType: 'detail'
})

ecBasketItem

Basket events should be emitted on every page as long as there are one or more items in the basket. They should not be emitted on an order summary page. There are two types of basket events that are emitted, ecBasketItem and ecBasketSummary.

Individual items are emitted as ecBasketItem events, each of which contains the summary for the full basket. This denormalization is essential for query performance.

After emitting one or more ecBasketItem events, a ecBasketSummary event should be emitted.

INFO: If item level detail is not known, it is acceptable to emit just an ecBasketSummary event without any ecBasketItem events.

Fields
  • basket.idstring
    Unique basket Id
  • The basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The basket total after the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The number of items in the basket
  • The basket subtotal, including tax, but before the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • Unique product identifier to distinguish each product from all of the other size, color, pattern, material, age, group, gender variants
  • The product’s name, which should match the name shown on the product page
  • An accurate description of the product, which should match the description on the product page
  • A list of one or more product categories this product belongs to. Each category is a full path of a category where each level is separated by >

  • The price that the product is currently being sold at, after discounts
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The price of the product before discounts, promotions
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The fully qualified URL that the product is shown on
  • An array of fully qualified image URLs for the product. The main image you want to use to display the product must be the first element in the array
  • The product manufacturer, recommended when a product inventory includes multiple brands
  • The color of the product
  • The size of the product, e.g. 12, M, XL, 14
  • quantitynumber
    The number of products described by the line item
  • The subtotal of the products described by the line item taking into account the current price and quantity before the application of taxes, discounts, promotions, shipping costs, etc.
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The subtotal of the products described by the line item taking into account the current price and quantity including tax, but before the application of discounts, promotions, shipping costs, etc.
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
uv.emit('ecBasketItem', {
  basket: {
    id: 'BASK123',
    subtotal: {
      value: 9.99,
      currency: 'USD'
    },
    total: {
      value: 9.99,
      currency: 'USD'
    },
    quantity: 10,
    subtotalIncludingTax: {
      value: 9.99,
      currency: 'USD'
    }
  },
  product: {
    sku: 'DRESS101-12',
    name: 'Red Cocktail Dress',
    description: 'This red cocktail dress is perfect for any occasion',
    categories: [
      'Clothing > Sweaters > Short Sleeve Sweaters',
      'New Arrivals > Clothing'
    ],
    price: {
      value: 9.99,
      currency: 'USD'
    },
    originalPrice: {
      value: 9.99,
      currency: 'USD'
    },
    url: 'http://www.fashionunion.com/dresses/red-cocktail-dress.html',
    images: [
      'http://www.fashionunion.com/dresses/red-cocktail-dress-1.jpg',
      'http://www.fashionunion.com/dresses/red-cocktail-dress-2.jpg'
    ],
    manufacturer: 'Dress Inc',
    color: 'Red',
    size: '12'
  },
  quantity: 2,
  subtotal: {
    value: 9.99,
    currency: 'USD'
  },
  subtotalIncludingTax: {
    value: 9.99,
    currency: 'USD'
  }
})

ecBasketItemAction

Emitted for every interaction with the basket, using the action field to specify whether a line item was added or removed. The event should also contain the summary for the full basket. This denormalization is essential for query performance.

After emitting one or more ecBasketItem events, a ecBasketSummary event should be emitted.

INFO: If item level detail is not known, it is acceptable to emit just an ecBasketSummary event without any ecBasketItemevents.

Fields
  • Id to identify a product, normally covering all of its size, color, pattern, and material variants
  • Unique product identifier to distinguish each product from all of the other size, color, pattern, material, age, group, gender variants
  • actionstring
    Can be either 'add', 'remove' for status changes
uv.emit('ecBasketItemAction', {
  product: {
    productId: 'DRESS101',
    sku: 'DRESS101-12'
  },
  action: 'add'
})

ecBasketItemTransaction

Transaction events are important because they report revenue for your website. They are set up in a similar way to basket events, except you should only emit them on a confirmation page, and they must include transaction.id.

The fields you emit to report what products the customer has purchased should be well aligned with the fields you emit in the ecBasketTransactionSummaryevent, which is emitted on the same page.

Fields
  • basket.idstring
    Unique basket Id
  • The basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The basket total after the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The basket subtotal, including tax, but before the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • Id to identify a product, normally covering all of its size, color, pattern, and material variants
  • Unique product identifier to distinguish each product from all of the other size, color, pattern, material, age, group, gender variants
  • The product’s name, which should match the name shown on the product page
  • An accurate description of the product, which should match the description on the product page
  • A list of one or more product categories this product belongs to. Each category is a full path of a category where each level is separated by >

  • The price that the product is currently being sold at, after discounts
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The price of the product before discounts, promotions
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The fully qualified URL that the product is shown on
  • An array of fully qualified image URLs for the product. The main image you want to use to display the product must be the first element in the array
  • The product manufacturer, recommended when a product inventory includes multiple brands
  • The color of the product
  • The size of the product, e.g. 12, M, XL, 14
  • quantitynumber
    The number of products described by the line item
  • The subtotal of the products described by the line item taking into account the current price and quantity before the application of taxes, discounts, promotions, shipping costs, etc.
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The subtotal of the products described by the line item taking into account the current price and quantity including tax, but before the application of discounts, promotions, shipping costs, etc.
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • An Id unique to the transaction
uv.emit('ecBasketItemTransaction', {
  basket: {
    id: 'BASK123',
    subtotal: {
      value: 9.99,
      currency: 'USD'
    },
    total: {
      value: 9.99,
      currency: 'USD'
    },
    subtotalIncludingTax: {
      value: 9.99,
      currency: 'USD'
    }
  },
  product: {
    productId: 'DRESS101',
    sku: 'DRESS101-12',
    name: 'Red Cocktail Dress',
    description: 'This red cocktail dress is perfect for any occasion',
    categories: [
      'Clothing > Sweaters > Short Sleeve Sweaters',
      'New Arrivals > Clothing'
    ],
    price: {
      value: 9.99,
      currency: 'USD'
    },
    originalPrice: {
      value: 9.99,
      currency: 'USD'
    },
    url: 'http://www.fashionunion.com/dresses/red-cocktail-dress.html',
    images: [
      'http://www.fashionunion.com/dresses/red-cocktail-dress-1.jpg',
      'http://www.fashionunion.com/dresses/red-cocktail-dress-2.jpg'
    ],
    manufacturer: 'Dress Inc',
    color: 'Red',
    size: '12'
  },
  quantity: 2,
  subtotal: {
    value: 9.99,
    currency: 'USD'
  },
  subtotalIncludingTax: {
    value: 9.99,
    currency: 'USD'
  },
  transaction: {
    id: '83748372'
  }
})

ecBasketTransactionSummary

This event collects a summary of information about the transaction. Importantly, this event is used to count conversions and the associated revenue. The event must include a transaction.id and the basket total.

Fields
  • The basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The basket total after the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The number of items in the basket
  • The basket subtotal, including tax, but before the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • An Id unique to the transaction
uv.emit('ecBasketTransactionSummary', {
  basket: {
    subtotal: {
      value: 9.99,
      currency: 'USD'
    },
    total: {
      value: 9.99,
      currency: 'USD'
    },
    quantity: 10,
    subtotalIncludingTax: {
      value: 9.99,
      currency: 'USD'
    }
  },
  transaction: {
    id: '83748372'
  }
})

ecBasketSummary

Emitted each time the basket is shown to the visitor either as an inline minibasket or in a view that shows only the basket. If the visitor's basket is changed in any way, the summary is emitted again.

After emitting one or more ecBasketItem events, a ecBasketSummary event should be emitted. If item level detail is not known, it is acceptable to emit just an ecBasketSummary event.

Fields
  • The basket value before the application of taxes, discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The basket total after the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
  • The number of items in the basket
  • The basket subtotal, including tax, but before the application of discounts, promotions, shipping costs, etc
  • Depending on the context, this could be the value of the basket, product, package, total, subtotal, discount, shipping, item, game, bet, etc. Please refer to our setup docs for more specific details for each vertical and event
  • The ISO 4217 currency e.g. GBP, USD
uv.emit('ecBasketSummary', {
  basket: {
    subtotal: {
      value: 9.99,
      currency: 'USD'
    },
    total: {
      value: 9.99,
      currency: 'USD'
    },
    quantity: 10,
    subtotalIncludingTax: {
      value: 9.99,
      currency: 'USD'
    }
  }
})