IntegrationsPlatform Solutions

Big Open Data Layer for Storefront Analytics

The Big Open Data Layer (shortened as BODL, pronounced ‘Bottle’) is a JavaScript object that simplifies sending data from BigCommerce-hosted storefronts to third-party analytics providers. It gives third-party scripts access to clean, consistent data. BODL makes store sites more efficient by consolidating data of interest and presenting it as a package. Each analytics script does not need to fetch the same data independently.

BODL is event-based. Scripts can capture accurate storefront data as it exists at the moment a shopper triggers any BODL-supported event.

This guide illustrates the basics of using BODL data in your integration. This article does the following:

  1. Describes the standard BODL schema after a shopper triggers a specified event so that you can see how BODL organizes event data for your integration to capture.
  2. Provides an example script that uses the standard BODL object so you can examine BODL properties in the browser console.
  3. Gives an example of adding a BODL script to a storefront page using the Scripts API.

Prerequisites

For scripts to successfully use BODL to access storefront data, the following must be true:

BODL event schemas

BODL exposes data when shoppers trigger storefront events. Currently, BODL supports the following storefront events:

If a merchant enables the consent banner, the following fields appear in the BODL object for the bodl_v1_loaded_consent event when a page loads:

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
advertisingbooleanIndicates whether the shopper consented to cookies that allow merchants to create personalized shopper content or profiles.Set cookie consent preferences
analyticsbooleanIndicates whether the shopper consented to cookies that provide statistical information on site usage.Set cookie consent preferences
functionalbooleanIndicates whether the shopper consented to cookies that enable enhanced functionality.Set cookie consent preferences

If a shopper changes the cookie consent settings, the following fields appear in the BODL object for the bodl_v1_update_consent event:

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
advertisingbooleanIndicates whether the shopper consented to cookies that allow merchants to create personalized shopper content or profiles.Set cookie consent preferences
analyticsbooleanIndicates whether the shopper consented to cookies that provide statistical information on site usage.Set cookie consent preferences
functionalbooleanIndicates whether the shopper consented to cookies that enable enhanced functionality.Set cookie consent preferences

When the shopper enters search keywords and clicks Enter or presses the search button, the following fields appear in the BODL object for the bodl_v1_keyword_search event:

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where the event is taking place.Get all channels
data.id
search_keyword stringKeywords used for the search.No mapping

View banner

When a shopper views a storefront banner, the following fields appear in the BODL object for the bodl_v1_view_banner event:

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where the event is taking place.Get all channels
data.id
banner_idstringID of the banner.Get all banners
id
banner_namestringBanner name.Get all banners
name

View product category

When the shopper clicks a button to view the category page for a product, the following fields appear in the BODL object for the bodl_v1_product_category_viewed event:

Event fieldTypeDescriptionBigCommerce data map
category_idintegerID of the category.Get all categories
data.id
category_namestringName of the category.Get all categories
data.name
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsItems in the category.See line_item object for event fields

View product page

When the shopper clicks a button to view a product page, the following fields appear in the BODL object for the bodl_v1_product_page_viewed event:

Event fieldTypeDescriptionBigCommerce data map
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code for the currency the storefront displays to shoppers.Get all currencies
currency_code
product_valuenumberPrice of the product before taxes; tax-exclusive price.Get prices
data.calculated_price.tax_exclusive
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsItem on the product page.See line_item object for event fields

Add product to cart

When the shopper clicks a button to add a product to a cart, the following fields appear in the BODL object for the bodl_v1_cart_product_added event:

Event fieldTypeDescriptionBigCommerce data map
channel_idstringThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsItems added to the cart.See line_item object for event fields
product_valuenumberItem price multiplied by quantity. Product default price or, if applicable, the sale price configured in the admin panel, before discounts and coupons are applied.Get a cart
lineItems.physicalItems.listPrice or
lineItems.digitalItems.listPrice

View cart

When the shopper clicks a button to view a cart, the following fields appear in the BODL object for the bodl_v1_cart_viewed event:

Event fieldTypeDescriptionBigCommerce data map
cart_valuenumberFinal value of cart after taxes, discounts, and coupons are applied.Get a cart
cartAmount
channel_idstringThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsAll items in the cart.See line_item object for event fields

Remove product from cart

When the shopper clicks a button to remove a product from the cart, the following fields appear in the BODL object for the bodl_v1_cart_product_removed event:

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
product_valuenumberItem price multiplied by quantity. Product default price or, if applicable, the sale price configured in the admin panel, before discounts and coupons are applied.Get a cart
lineItems.physicalItems.listPrice or
lineItems.digitalItems.listPrice
channel_idstringThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
line_items[]array of line_item objectsItems removed from the cart.See line_item object for event fields

Start checkout

When the shopper clicks on the button to initiate a checkout process, the following fields appear in the BODL object for the bodl_v1_begin_checkout event:

Event fieldTypeDescriptionBigCommerce data map
cart_valuenumberFinal value of cart after taxes, discounts, and coupons are applied.Get a cart
cartAmount
channel_idstringThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
coupon_codes[]array of stringsCoupon codes applied to the cart. BigCommerce supports only one coupon code per checkout.Get a cart
coupons.code
currencystringISO-4217 currency code of the order. BigCommerce tracks currency for a cart and not for each line item within the cart.Get a cart
currency.code
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsItems that were checked out.See line_item object for event fields

Add shipping information

Each time the shopper adds shipping information, the following fields appear in the BODL object for the bodl_v1_shipping_information_added event. This event can trigger multiple times for a single order.

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
cart_valuenumberFinal value of cart after taxes, discounts, and coupons are applied.Get a checkout
data.cart.cart_amount_inc_tax
coupon_codes[]array of stringsCoupon codes applied to the purchase. BigCommerce supports only one coupon code per checkout.Get a checkout
data.cart.coupons.code
shipping_methodstringShipping method, for example, UPS or First Class Mail.Get order shipments
shipping_method
line_items[]array of line_item objectsItems that were checked out.See line_item object for event fields

Add payment information

Each time the shopper adds payment information, the following fields appear in the BODL object for the bodl_v1_payment_information_added event. This event can trigger multiple times for a single order.

Event fieldTypeDescriptionBigCommerce data map
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
cart_valuenumberFinal value of cart after taxes, discounts, and coupons are applied.Get a checkout
data.cart.cart_amount_inc_tax
coupon_codes[]array of stringsCoupon codes applied to the purchase. BigCommerce supports only one coupon code per checkout.Get a checkout
data.cart.coupons.code
payment_typestringPayment type, for example, check or credit card.Get an order
payment_method
line_items[]array of line_item objectsItems that were checked out.See line_item object for event fields

Purchase order

When the shopper clicks a button to finalize a purchase, the following fields appear in the BODL object for the bodl_v1_order_purchased event:

Event fieldTypeDescriptionBigCommerce data map
cart_valuenumberFinal value of cart after taxes, discounts, and coupons are applied.Get a checkout
data.cart.cart_amount_inc_tax
channel_idintegerThe BigCommerce channel ID. Channel ID of the channel where checkout is taking place.Get all channels
data.id
coupon_codes[]array of stringsCoupon codes applied to the purchase. BigCommerce supports only one coupon code per order.Get a checkout
data.cart.coupons.code
currencystringISO-4217 currency code of the order.Get a checkout
data.cart.currency.code
event_idstringUnique ID for each event instance.Unique event ID generated by BigCommerce.
line_items[]array of line_item objectsItems that were purchased.See line_item object for event fields
order_idintegerUnique order ID generated by BigCommerce.Get a checkout
data.orderId
shipping_costnumberTotal shipping cost including tax.Get a checkout
data.shipping_cost_total_inc_tax
taxnumberTax incurred.Get a checkout
data.taxTotal

line_item object schema

The line_item object has many common fields for browser events, including the following fields:

Event fieldTypeDescriptionBigCommerce data map
base_pricenumberPrice of product. Default price in the control panel. The price should include or exclude tax, based on the store settings.Get a product
data.price
brand_namestringBrand name.Get a product
data.brand_name
category_names[]array of stringsCategory names.Get a product
data.categories[]
coupon_amountnumberThe total value of all coupons applied to this item.Get a checkout
cart.lineItems.physicalItems.couponAmount or cart.lineItems.digitalItems.couponAmount
currencystringISO-4217 currency code for the transaction.Get a checkout
data.cart.currency.code
discountnumberDiscount applied to the purchase.Get a checkout
cart.lineItems.physicalItems.discountAmount or cart.lineItems.digitalItems.discountAmount
gift_certificate_idstringID of gift certificate.Get a cart
lineItems.giftCertificates.id
gift_certificate_namestringName of gift certificate that appears in the control panel.Get a Cart
lineItems.giftCertificates.name
gift_certificate_themestringTheme of gift certificate.Get a cart
lineItems.giftCertificates.theme
product_idstringID of the product.Get a product
data.id
product_namestringName of the product.Get a product
data.name
purchase_pricenumberFinal price of product that the shopper actually pays before taxes and other charges. Equals the base_price unless there is a sale_price. The price should include or exclude tax, based on the store settings.Get a product
data.price or
data.sale_price
quantityintegerNumber of items of product purchased.Get a cart
lineItems.physicalItems.quantity or
lineItems.digitalItems.quantity
retail_pricenumberThe retail price of the product. The price should include or exclude tax, based on the store settings.Get a product
data.retail_price
sale_pricenumberPrice of product after sale. The price should include or exclude tax, based on the store settings.Get a product
data.sale_price
skustringUser-defined SKU for the product or variant (whichever is applied).Get a product
data.sku or data.variants.sku
variant_idstringID of the variant.Get a product
data.variants.id

Example implementation

You can use the Scripts API or control panel Script Manager to add scripts to a BigCommerce-hosted storefront.

Merchants must enable BODL in the store control panel for your script to subscribe to BODL events. Once BODL is enabled, BigCommerce checks every storefront page for the BODL object once per page render.

Example script

To view BODL properties in the browser console, use the following example script:

Log BODL to the browser console
<script>
function subscribeOnBodlEvents() {
  // log to verify that the function is executing
  console.log('run subscribeOnBodlEvents()');
  if (
    // window is falsy
    !window ||
    // window.bodlEvents is not defined
    typeof window.bodlEvents === 'undefined' ||
    // window.bodlEvents.banner is not defined
    typeof window.bodlEvents.banner === 'undefined' ||
    // window.bodlEvents.checkout is not defined
    typeof window.bodlEvents.checkout === 'undefined' ||
    // window.bodlEvents.cart is not defined
    typeof window.bodlEvents.cart === 'undefined' ||
    // window.bodlEvents.product is not defined
    typeof window.bodlEvents.product === 'undefined' ||
    // window.bodlEvents.consent is not defined
    typeof window.bodlEvents.consent === 'undefined'  
  ) {
    // log 'not defined' to the console
    console.log('not defined');
    // and end script execution
    return;
  }
  // if window.dataLayer doesn't exist, make it an empty array
  window.dataLayer = window.dataLayer || [];
  // If window.bodlEvents.consent.loaded is available, then...
  if (typeof window.bodlEvents.consent.loaded === 'function') {
    // run the loaded function to get the payload
    window.bodlEvents.consent.loaded((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.consent.loaded ~ payload',
        payload
      );
    });
  }
 
  // If window.bodlEvents.consent.updated is available, then...
  if (typeof window.bodlEvents.consent.updated === 'function') {
    // run the updated function to get the payload
    window.bodlEvents.consent.updated((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.consent.updated ~ payload',
        payload
      );
    });
  } 
  // If window.bodlEvents.product.searchPerformed is available, then...
  if (typeof window.bodlEvents.product.searchPerformed === 'function') {
    // run the searchPerformed function to get the payload
    window.bodlEvents.product.searchPerformed((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.product.searchPerformed ~ payload',
        payload
      );
    });
  }    
  // If window.bodlEvents.banner.viewed is available, then...
  if (typeof window.bodlEvents.banner.viewed === 'function') {
    // run the viewed function to get the payload
    window.bodlEvents.banner.viewed((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.banner.viewed ~ payload',
        payload
      );
    });
  }    
  // If window.bodlEvents.product.pageViewed is available, then...
  if (typeof window.bodlEvents.product.pageViewed === 'function') {
    // run the pageViewed function to get the payload
    window.bodlEvents.product.pageViewed((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.product.pageViewed ~ payload',
        payload
      );
    });
  }
    
  // If window.bodlEvents.product.categoryViewed is available, then...
  if (typeof window.bodlEvents.product.categoryViewed === 'function') {
    // run the categoryViewed function to get the payload
    window.bodlEvents.product.categoryViewed((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.product.categoryViewed ~ payload',
        payload
      );
    });
  }
    
  // If window.bodlEvents.cart.addItem is available, then...
  if (typeof window.bodlEvents.cart.addItem === 'function') {
    // run the addItem function to get the payload
    window.bodlEvents.cart.addItem((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.cart.addItem ~ payload',
        payload
      );
    });
  }
    
  // If window.bodlEvents.cart.viewed is available, then...
  if (typeof window.bodlEvents.cart.viewed === 'function') {
    // run the viewed function to get the payload
    window.bodlEvents.cart.viewed((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.cart.viewed ~ payload',
        payload
      );
    });
  }
    
  // If window.bodlEvents.cart.removeItem is available, then...
  if (typeof window.bodlEvents.cart.removeItem === 'function') {
    // run the removeItem function to get the payload
    window.bodlEvents.cart.removeItem((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.cart.removeItem ~ payload',
        payload
      );
    });
  }
    
  //   If window.bodlEvents.checkout.checkoutBegin is available, then...
  if (typeof window.bodlEvents.checkout.checkoutBegin === 'function') {
    // run the checkoutBegin function to get the payload
    window.bodlEvents.checkout.checkoutBegin((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.checkout.checkoutBegin ~ payload',
        payload
      );
    });    
  }
  // If window.bodlEvents.checkout.shippingDetailsProvided is available, then...
  if (typeof window.bodlEvents.checkout.shippingDetailsProvided === 'function') {
    // run the shippingDetailsProvided function to get the payload
    window.bodlEvents.checkout.shippingDetailsProvided((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.checkout.shippingDetailsProvided ~ payload',
        payload
      );
    });
  }
  // If window.bodlEvents.checkout.paymentDetailsProvided is available, then...
  if (typeof window.bodlEvents.checkout.paymentDetailsProvided === 'function') {
    // run the paymentDetailsProvided function to get the payload
    window.bodlEvents.checkout.paymentDetailsProvided((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.checkout.paymentDetailsProvided ~ payload',
        payload
      );
    });
  }
  // If window.bodlEvents.checkout.orderPurchased is available, then...
  if (typeof window.bodlEvents.checkout.orderPurchased === 'function') {
    // run the orderPurchase function to get the payload
    window.bodlEvents.checkout.orderPurchased((payload) => {
      // log the event payload
      console.log(
        'window.bodlEvents.checkout.orderPurchased ~ payload',
        payload
      );
    });
  }
}
// when the page window loads, run the subscribeOnBodlEvents function
window.addEventListener('load', subscribeOnBodlEvents, false);
</script>

If a merchant enables cookie tracking consent, the shopper must provide consent to the category of consent (consent_category) to which the script is set. For more on consent categories, see the Script Manager support article.

Scripts API example

The following is an example request that uses the Scripts API to associate the example script with pages on a storefront. Send a request to the Create a script endpoint. For more, see the Scripts API article.

Example request: Create a Script
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/scripts
X-Auth-Token: {{ACCESS_TOKEN}}     //scope should include Checkout Content when adding script to a checkout page
Content-Type: application/json
Accept: application/json
{
  "name": "BODL script",
  "description": "view BODL in the browser console",
  "html": "<script> function subscribeOnBodlEvents() {console.log('run subscribeOnBodlEvents()'); window.dataLayer = window.dataLayer || []; if (!window || typeof window.bodlEvents === 'undefined' || typeof window.bodlEvents.checkout === 'undefined') {console.log('not defined'); return;} if (typeof window.bodlEvents.checkout.checkoutBegin === 'function') {window.bodlEvents.checkout.checkoutBegin((payload) => {console.log('window.bodlEvents.checkout.checkoutBegin ~ payload', payload);});} if (typeof window.bodlEvents.checkout.orderPurchased === 'function') {window.bodlEvents.checkout.orderPurchased((payload) => {console.log('window.bodlEvents.checkout.orderPurchased ~ payload', payload);});}}  window.addEventListener('load', subscribeOnBodlEvents, false); </script>",
  "load_method": "default",
  "location": "head",
  "visibility": "all_pages",            //set which pages can access the script
  "kind": "script_tag",
  "consent_category": "essential",      //script is set to a category of consent
  "enabled": true,
  "channel_id": 2                       //storefront channel ID
}

Resources