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:
- 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.
- Provides an example script that uses the standard BODL object so you can examine BODL properties in the browser console.
- 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:
- Enable BODL on the subject storefront using the control panel or the GraphQL Admin API's Enable data layer mutation
- The storefront must use a stencil theme
BODL event schemas
BODL exposes data when shoppers trigger storefront events. Currently, BODL supports the following storefront events:
- Load consent
- Update consent
- Keyword search
- View banner
- View product page
- View product category
- Add product to cart
- View cart
- Remove product from cart
- Start checkout
- Add shipping information
- Add payment information
- Purchase order
Load consent
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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
advertising | boolean | Indicates whether the shopper consented to cookies that allow merchants to create personalized shopper content or profiles. | Set cookie consent preferences |
analytics | boolean | Indicates whether the shopper consented to cookies that provide statistical information on site usage. | Set cookie consent preferences |
functional | boolean | Indicates whether the shopper consented to cookies that enable enhanced functionality. | Set cookie consent preferences |
Update consent
If a shopper changes the cookie consent settings, the following fields appear in the BODL object for the bodl_v1_update_consent
event:
Event field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
advertising | boolean | Indicates whether the shopper consented to cookies that allow merchants to create personalized shopper content or profiles. | Set cookie consent preferences |
analytics | boolean | Indicates whether the shopper consented to cookies that provide statistical information on site usage. | Set cookie consent preferences |
functional | boolean | Indicates whether the shopper consented to cookies that enable enhanced functionality. | Set cookie consent preferences |
Keyword search
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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where the event is taking place. | Get all channels data.id |
search_keyword | string | Keywords 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where the event is taking place. | Get all channels data.id |
banner_id | string | ID of the banner. | Get all banners id |
banner_name | string | Banner 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
category_id | integer | ID of the category. | Get all categories data.id |
category_name | string | Name of the category. | Get all categories data.name |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | Items 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) for the currency the storefront displays to shoppers. | Get all currencies currency_code |
product_value | number | Price of the product before taxes; tax-exclusive price. | Get prices data.calculated_price.tax_exclusive |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | Item 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
channel_id | string | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | Items added to the cart. | See line_item object for event fields |
product_value | number | Item 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
cart_value | number | Final value of cart after taxes, discounts, and coupons are applied. | Get a cart cartAmount |
channel_id | string | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | All 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
product_value | number | Item 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_id | string | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
line_items[] | array of line_item objects | Items 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
cart_value | number | Final value of cart after taxes, discounts, and coupons are applied. | Get a cart cartAmount |
channel_id | string | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
coupon_codes[] | array of strings | Coupon codes applied to the cart. BigCommerce supports only one coupon code per checkout. | Get a cart coupons.code |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. BigCommerce tracks currency for a cart and not for each line item within the cart. | Get a cart currency.code |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | Items 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
cart_value | number | Final value of cart after taxes, discounts, and coupons are applied. | Get a checkout data.cart.cart_amount_inc_tax |
coupon_codes[] | array of strings | Coupon codes applied to the purchase. BigCommerce supports only one coupon code per checkout. | Get a checkout data.cart.coupons.code |
shipping_method | string | Shipping method, for example, UPS or First Class Mail. | Get order shipments shipping_method |
line_items[] | array of line_item objects | Items 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
cart_value | number | Final value of cart after taxes, discounts, and coupons are applied. | Get a checkout data.cart.cart_amount_inc_tax |
coupon_codes[] | array of strings | Coupon codes applied to the purchase. BigCommerce supports only one coupon code per checkout. | Get a checkout data.cart.coupons.code |
payment_type | string | Payment type, for example, check or credit card. | Get an order payment_method |
line_items[] | array of line_item objects | Items 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
cart_value | number | Final value of cart after taxes, discounts, and coupons are applied. | Get a checkout data.cart.cart_amount_inc_tax |
channel_id | integer | The BigCommerce channel ID. Channel ID of the channel where checkout is taking place. | Get all channels data.id |
coupon_codes[] | array of strings | Coupon codes applied to the purchase. BigCommerce supports only one coupon code per order. | Get a checkout data.cart.coupons.code |
currency | string | ISO-4217 currency code (opens in a new tab) of the order. | Get a checkout data.cart.currency.code |
event_id | string | Unique ID for each event instance. | Unique event ID generated by BigCommerce. |
line_items[] | array of line_item objects | Items that were purchased. | See line_item object for event fields |
order_id | integer | Unique order ID generated by BigCommerce. | Get a checkout data.orderId |
shipping_cost | number | Total shipping cost including tax. | Get a checkout data.shipping_cost_total_inc_tax |
tax | number | Tax 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 field | Type | Description | BigCommerce data map |
---|---|---|---|
base_price | number | Price 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_name | string | Brand name. | Get a product data.brand_name |
category_names[] | array of strings | Category names. | Get a product data.categories[] |
coupon_amount | number | The total value of all coupons applied to this item. | Get a checkout cart.lineItems.physicalItems.couponAmount or cart.lineItems.digitalItems.couponAmount |
currency | string | ISO-4217 currency code (opens in a new tab) for the transaction. | Get a checkout data.cart.currency.code |
discount | number | Discount applied to the purchase. | Get a checkout cart.lineItems.physicalItems.discountAmount or cart.lineItems.digitalItems.discountAmount |
gift_certificate_id | string | ID of gift certificate. | Get a cart lineItems.giftCertificates.id |
gift_certificate_name | string | Name of gift certificate that appears in the control panel. | Get a Cart lineItems.giftCertificates.name |
gift_certificate_theme | string | Theme of gift certificate. | Get a cart lineItems.giftCertificates.theme |
product_id | string | ID of the product. | Get a product data.id |
product_name | string | Name of the product. | Get a product data.name |
purchase_price | number | Final 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 |
quantity | integer | Number of items of product purchased. | Get a cart lineItems.physicalItems.quantity or lineItems.digitalItems.quantity |
retail_price | number | The retail price of the product. The price should include or exclude tax, based on the store settings. | Get a product data.retail_price |
sale_price | number | Price of product after sale. The price should include or exclude tax, based on the store settings. | Get a product data.sale_price |
sku | string | User-defined SKU for the product or variant (whichever is applied). | Get a product data.sku or data.variants.sku |
variant_id | string | ID of the variant. | Get a product data.variants.id |
Example implementation
You can use the Scripts API or control panel Script Manager (opens in a new tab) 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:
<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>
Category of consent
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 (opens in a new tab) 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.
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
- Scripts overview
- REST Management API: Scripts reference
- Using Script Manager (Help Center) (opens in a new tab)