Breville Decision Tool (widgets) Integration

Background

Breville | Sage Appliances have a number of guided product selection tools to help customer choose the right appliance for their needs. These tools have been made available for retail partners to easily integrate into their retail websites. This guide provides the technical details of how this can be achieved and what widgets and products are available / need to be mapped with to your (the retailers) prices and product landing pages. Demonstrations for each widget can be found at https://prod-widgets.breville.com

Solution

The breville-widget is a general Web Component that allows to host a Breville Widget inside an iFrame on your (3rd party/retailer) website. The code is necessary to control an iframe and create a communication bridge to pass critical information to the widget around pricing, styling and product pages. The widget also sends back information to resize the height of the iframe appropriately. Once the widget is placed on your site, the:

1. breville-widget renders an iFrame with a link to a Breville / Sage Appliances Decision tool that is hosted on https://prod-widgets.breville.com

2. breville-widget uses postMessage calls to configure the widget inside an iFrame and to pass widget configuration for locale/language, styling, product range, product page URL’s, and prices to the widget.

3. A domain white-listing policy has been applied to minimise the risk of improper use of the decision tool and thus you (the retailer) must ask to be added to that whitelist

4. The breville-widget has been designed with security in mind to reduce the attack surface and the possibility of a widget somehow breaking the retailers site. All the widget code run inside an iframe and the breville-widget is just the glue to ensure the iframe is correctly setup and resized on the retailer’s site and to ensure it does not block the rest of the page from loading.

Installation

There is a 3 step installation process

1. Contact Breville and ensure that your domain has been properly whitelisted so that the component is allowed to run on your site/domain. If you do not do this it will not work.

2. breville-widget JavaScript to the bottom of your page.

<!--====== Breville Widget js ======-->
<script src="//widgets.breville.com/etc/designs/bvl-widgets/bridge-widget/js/app.js"></script>

3. Add breville-widget-v1 snippet on the page and configure it. The breville-widget-v1 Web Component accepts the following parameters:

• type- The type of widget. - a list of widget types in provided within this document

• locale - The widget locale - a list of applicable locales is provided within this document

• topoffset - At times the widget will need to scroll up to relieve the top of the widget. If you have a sticky header, your header may overlap the widget. In such case, provide the number of pixels the header takes up so the top of the widget is below the bottom of your sticky header.

• JSON script element “<script type="application/json">“ that must have:

  • env - URL where widget is hosted (this should always be set to prod-widgets.breville.com

  • props with

  • an optional styles property to style the widget

  • a mpns property to send product mappings, prices, and availability information to the widget. This is a mandatory property to configure where each recommended product resides on your site, it’s price and availability. Each entry is defined by the Breville product parent SKU on the Breville website, but will eventually be the official manufacture product number (MPN). Please refer to specific widget examples for products and structure.

  
  

"env": "prod-widgets.breville.com ",

Configuration examples

Configuration example for Espresso is shown below. This structure is also applicable for Tea, Waves, Smart Ovens, Air & Water decision tools, but requires different type and mpns.

<breville-widget-v1 type="espresso-widget" locale="us/en">
<script type="application/json">
{
"env": "prod-widgets.breville.com",
"props": {
"mpns": {
"BES500": {
"url": "https://www.your_site.com/your_BES500_product_page/",
"price": "$9111.11"
},
"BES840": {
"url": "https://www.your_site.com/your_BES840_product_page/",
"default": 1,
"price": "$9222.22"
},
"BES870": {
"url": "https://www.your_site.com/your_BES870_product_page/",
"default": 2,
"price": "$9333.33"
},
"BES878": {
"url": "https://www.your_site.com/your_BES878_product_page/",
"price": "$9444.44"
},
"BES880": {
"url": "https://www.your_site.com/your_BES880_product_page/",
"price": "$9555.55"
},
"BES920": {
"url": "https://www.your_site.com/your_BES920_product_page/",
"price": "$9666.66"
},
"BES980": {
"url": "https://www.your_site.com/your_BES980_product_page/",
"price": "$9777.77"
},
"BES990": {
"url": "https://www.your_site.com/your_BES990_product_page/",
"price": "$9888.88"
}
}
}
}
</script>
</breville-widget-v1>

Configuration example for the “Colour Me Healthy” (Blend, Juice or Bluice) shown below.

Note: the inclusion of product categories, must be maintained. If no products are ranged by the retailer then the category (bluicing, blender etc) should be left empty to avoid warning in the console log.

<breville-widget-v1 type="cmh-widget" locale="us/en">
<script type="application/json">
{
"env": "prod-widgets.breville.com",
"props": {
"mpns": {
"bluicing": {
"BJB815": {
"url": "https://www.breville.com/en-us/product/bjb815",
"price": "$1111.01"
}
},
"blenders": {
"BBL920": {
"url": "https://www.breville.com/en-us/product/bbl920",
"price": "$1111.02"
},
"BBL820": {
"url": "https://www.breville.com/en-us/product/bbl820",
"price": "$2222.02"
},
"BBL620": {
"url": "https://www.breville.com/en-us/product/bbl620",
"price": "$3333.02"
},
"BPB610": {
"url": "https://www.breville.com/en-us/product/bpb610",
"price": "$4444.02"
},
"BBL002": {
"url": "https://www.breville.com/en-us/product/bbl002",
"price": "$5555.02"
}
},
"fast_juicers": {
"BJE820": {
"url": "https://www.breville.com/en-us/product/bje820",
"price": "$1111.03"
},
"BJE830": {
"url": "https://www.breville.com/en-us/product/bje830",
"price": "$2222.03"
},
"800JE": {
"url": "https://www.breville.com/en-us/product/800je",
"price": "$3333.03"
},
"BJE530": {
"url": "https://www.breville.com/en-us/product/bje530",
"price": "$4444.03"
},
"BJE430": {
"url": "https://www.breville.com/en-us/product/bje430",
"price": "$5555.03"
},
"JE98XL": {
"url": "https://www.breville.com/en-us/product/je98xl",
"price": "$6666.03"
},
"BJE200": {
"url": "https://www.breville.com/en-us/product/bje200",
"price": "$77777.03"
}
},
"slow_juicers": {
"BJS700": {
"url": "https://www.breville.com/en-us/product/bjs700",
"price": "$1111.04"
}
},
"citrus_presses": {
"800CP": {
"url": "https://www.breville.com/en-us/product/800cp",
"price": "$1111.05"
},
"BCP600": {
"url": "https://www.breville.com/en-us/product/bcp600",
"price": "$2222.05"
}
}
}
}
}
</script>
</breville-widget-v1>

Configuration example for the Your Perfect Brew tool shown below.

<breville-widget-v1 type="your-perfect-brew" locale="au/en">
<script type="application/json">
{
"env": "prod-widgets.breville.com",
"props": {
"link": {
"title": "View More",
"url": "https://breville.com/"
},
"}
</script>
</breville-widget-v1>

How to override a product’s description

Example of a product’s description (the burlywood background part)

If a retailer wishes to provide their own description for a specific product, add description’s value to that product’s mpn, for example:

"mpns": {
"BES500": {
"url": "https://www.your_site.com/your_BES500_product_page/",
"price": "$9111.11",
"description": "<p>this is the new description <strong>yo check this out</strong><p>"
},
...

You can use just simple text strings or rich text strings for description.

Decision tool type and locale parameters

The following widget types and locales are currently supported.

Applicable MPN’s for Each Tool Per locale

The following MPN’s can be included when setting up the configuration for each decision tool. Simply omit any MPN’s not included in the range on your retail website to avoid that product being recommended.

For each MPN added to the configuration, make sure both url and price information is provided. The example below shows all information required for each MPN for Espresso, Tea, Waves, Smart Ovens, Air & Water. For the “Blend, Juice or Bluce” (type="cmh-widget" each list of mpn need to be contained in a specific category (see separate example at end of document).

"BES500": {
"url": "https://www.your_site.com/your_BES500_product_page/,
"price": "$9111.11"
}

Espresso

*MPNs are case insensitive

Waves

Tea

Smart Ovens

Air

Water

Blend, Juice, Bluice

For each MPN added to the configuration for Blend, Juice, Bluice, make sure all information is provided, and MPN is placed under the correct product category.

If a product is not ranged, it can be omitted leaving the category blank (with no products) and thus removing causing the widget to never recommend that category. To avoid possible warnings in the console, we recommend to always have the list of categories (i.e bluicing, blenders etc) present even when they are empty.

*Product category naming must be maintained.

{
"mpns": {
"bluicing": {
"BJB815": {
"url": "https://www.your_site.com/your_product_page.html",
"price": "$1111.01"
}
},
"blenders": {
"BBL920": {
"url": "https://www.your_site.com/your_product_page.html",
"price": "$1111.02"
},
"fast_juicers": {
"BJE820": {
"url": "https://www.your_site.com/your_product_page.html",
"price": "$1111.03"
},
"slow_juicers": {
"BJS700": {
"url": "https://www.your_site.com/your_product_page.html",
"price": "$1111.04"
}
},
"citrus_presses": {
"800CP": {
"url": "https://www.your_site.com/your_product_page.html",
"price": "$1111.05"
}
}
}
}
}
}

Widget Security

The breville-widget has been designed with following security measures in place

1. A white-listing policy is applied across all widgets. This prevents any widget from loading unless it can verify that the retail website domain (URL) has been added to the list of acceptable domains under the policy.
a. To add you website domain(s) to the white-listing policy, please submit a request via email to your regional Breville/Sage Appliances contact stating all retail website domains where the widget / decision tools are intended to be used.

2. All widgets code runs within an iframe that is embedded on the retailer website via the script provided as part of this implementation guide. The script ensures the iframe is correctly setup to call & display widget content within the retailer site. Minimal code and changes are made to the breville-widget scripts.