Getting widget results
This page shows you an example request and response that can help you form your own widget API calls for your site. If you need more information about widget parameters, then take a look at the quick reference table, which describes the parameters and provides example values.
Tips
Search engine bots spend a limited time crawling your site. They often have rules about how deeply they crawl through your site hierarchy. Related categories, related items, and related products optimize your site by flattening your site from a linking perspective, making it easy to find your products.
Implement your related categories, related items, and related products in HTML. Search engines don't understand or value JavaScript and AJAX as highly as HTML content.
Request
During integration kickoff, Bloomreach gives you an example API request that's customized with your account information. You can use that example request by adding your own values to the remaining parameters.
GET https://<api_host>/v3/fetch_widget?
url=<url>
&acct_id=<acct_id>
&acct_auth=<acct_auth>
&ptype=<ptype>
&user_agent=<user_agent>
&ref=<ref>
&prod_id=<prod_id>
&prod_name=<prod_name>
&pstatus=<pstatus>
GET http://example.brsrvr.com/v3/fetch_widget
?url=http%3A//www.example.com/product%3Fid%3D999
&acct_id=<Bloomreach Provided Account ID>
&acct_auth=jazz_hands
&ptype=product
&user_agent=Mozilla%2F5.0+%28compatible%3B+Googlebot%29
&ref=http%3A//www.example.com/search%3Fq%3Fdresses
&prod_id=999
&prod_name=Colette%20red%20crepe%20peek-a-boo%20jacket%20dress
&pstatus=ok
Tip
Add the following header to your request so that you receive a compressed response:
Accept-Encoding: gzip, deflate.
If you are a Demandware Cartridge user, then you don't need to add this header.
Escape characters and encoding
You should escape non-alphanumeric characters in your parameter values using URL percent-encoding conventions. For example:
| Character | Escape |
|---|---|
| / | %2F |
| ( | %28 |
| ; | %3B |
| ) | %29 |
Values for query parameters that have multiple words can use URL percent-encoded spaces (%20) between the words. For example:
&fq=color:"light%20blue"
Escape double quotes
The values for some parameters, such as fq, require double quote marks ( " ) around them. If the value you're specifying includes double quotes, then you need to escape those double quotes with a backslash ( \ ) before the value's double quotes. For example:
&fq=size:"8.5\" by 11\""
Response
Bloomreach returns HTML in response to the request.
Compressed response
The response is gzip compressed. You need to uncompress the response to use the contents. If you are a Demandware Cartridge user, then your response is not compressed.
<script type="text/javascript">var br_related_rid = "Rwks1ximiagpi1w5tc1zu-uf,r1,m1";</script>
<script type="text/javascript">var br_iuid = "aHR0cDovL3d3dy5kb2xsYXJ0cmVlLmNvbS9vZmZpY2Utc2Nob29sL2xlYXJuaW5nLWVkdWNhdGlvbmFsL2NvbG9yaW5nLWFjdGl2aXR5LWJvb2tzLzYxMGM2MTZjNjIwL2luZGV4LmNhdA==";</script>
<!-- BEGIN RELATED-ITEM -->
<div id="br-related-items-widget">
<div class="br-ri-heading">Related Items</div>
<div class="br-ri">
<a class="br-ri-link" href="www.example.com/shoes/heels/4 and above">4-Inch and Much Higher Heels</a>
</div>
</div>
<!-- END RELATED-ITEM -->
<!-- BEGIN RELATED-CATEGORY -->
<div id="br-related-categories-widget">
<div class="br-rc-heading">Related Categories</div>
<div class="br-rc">
<a class="br-rc-link" href= "www.example.com/dresses/lbd">Little Black Dresses</a>
</div>
<div class="br-rc">
<a class="br-rc-link" href= "www.example.com/clothes/party">Fancy Party Dresses</a>
</div>
</div>
<!-- END RELATED-CATEGORY -->
<!-- BEGIN MORE-RESULTS -->
<div class="br-found-heading">Related Products</div>
<div class="br-sf-widget">
<div class="br-sf-widget-example-cont">
<div class="br-sf-widget-example-img">
<a href="http://www.example.com/product/tropical-blossoms.html">
<img src="http://www.example.com/image/tropical-blossoms.jpg">
</a>
</div>
<div class="br-sf-widget-example-title">
<a href="http://www.example.com/product/tropical-blossoms.html">
JUNIOR DRESS
</a>
</div>
<div class="br-sf-widget-example-desc">
This flowery dress breathes paradise ...
</div>
<div class="br-sf-widget-example-qv">
<a href="javascript:void(0);" onclick="showBrRpQv('br1')">
Quickview
</a>
</div>
</div>
</div>
<div id="br1" class="br-rp-qv-hide">
<div class="br-sf-widget-example-popup-maincont">
<div class="br-sf-widget-example-popup-cont">
<div class="br-sf-widget-example-popup-img">
<a href="http://www.example.com/product/tropical-blossoms.html">
<img src="http://www.example.com/image/tropical blossoms.jpg">
</a>
</div>
<div class="br-sf-widget-example-popup-title">
<a href="http://www.example.com/product/tropical-blossoms.html">
JUNIOR DRESS
</a>
</div>
<div class="br-sf-widget-example-popup-desc">
Description:
<br>
This flowery dress breathes paradise
into you casual wardrobe. It's lovely with tan sandals and a stroll along the boardwalk. Junior sizes only.
</div>
<div class="br-sf-widget-example-popup-view">
<a href="http://www.example.com/product/tropical-blossoms.html">
View Product
</a>
</div>
<div class="br-sf-widget-example-popup-close">
<a href="javascript:void(0);" onclick="hideBrRpQv();">
[ x ] close
</a>
</div>
</div>
</div>
</div>
<div class="br-sf-widget">
<div class="br-sf-widget-example-cont">
<div class="br-sf-widget-example-img">
<a href="http://www.example.com/product/blue-in-the-sun.html">
<img src="http://www.example.com/image/blue-in-the-sun.jpg">
</a>
</div>
<div class="br-sf-widget-example-title">
<a href="http://www.example.com/product/blue-in-the-sun.html">
WOMEN STRAPLESS CASUAL
</a>
</div>
<div class="br-sf-widget-example-desc">
Strapless abstract blue is perfect for ...
</div>
<div class="br-sf-widget-example-qv">
<a href="javascript:void(0);" onclick="showBrRpQv('br2')">
Quickview
</a>
</div>
</div>
</div>
<div id="br2" class="br-rp-qv-hide">
<div class="br-sf-widget-example-popup-maincont">
<div class="br-sf-widget-example-popup-cont">
<div class="br-sf-widget-example-popup-img">
<a href="http://www.example.com/product/blue-in-the-sun.html">
<img src="http://www.example.com/image/blue-in-the-sun.jpg">
</a>
</div>
<div class="br-sf-widget-example-popup-title">
<a href="http://www.example.com/product/blue-in-the-sun.html">
WOMEN STRAPLESS CASUAL
</a>
</div>
<div class="br-sf-widget-example-popup-desc">
Description:
<br>
Strapless abstract blue is perfect for
casual night life after a day at the beach. Dress it up with a bolero or leave your shoulders bare for a sultry look.
</div>
<div class="br-sf-widget-example-popup-view">
<a href="http://www.example.com/product/blue-in-the-sun.html">
View Product
</a>
</div>
<div class="br-sf-widget-example-popup-close">
<a href="javascript:void(0);" onclick="hideBrRpQv();">
[ x ] close
</a>
</div>
</div>
</div>
</div>
<div class="br-sf-widget">
...
</div>
<script type="text/javascript">
function hideBrRpQv() {
var elems = document.querySelectorAll(".br-rp-qv-show");
for (var i=0; i<elems.length; i++) {
// replace show class with hide class
var classStr = elems[i].getAttribute('class') + ' ';
classStr = classStr.replace('br-rp-qv-show ', 'br-rp-qv-hide ');
elems[i].setAttribute('class', classStr);
}
}
function showBrRpQv(id) {
// close existing popups, before showing current popup
hideBrRpQv();
// replace hide class with show class
var classStr = document.getElementById(id).getAttribute('class') + ' ';
classStr = classStr.replace('br-rp-qv-hide ', 'br-rp-qv-show ');
document.getElementById(id).setAttribute('class', classStr)
}
</script>
<!-- END MORE-RESULTS -->
Response processing
The body contains valid HTML that can be directly inserted in the page on the server side. This HTML is deliberately kept simple, offering maximum compatibility with the rest of your page.
Your call might not return any content for related categories, related items or related products. The response still contains the JavaScript variable, br_related_rid. Make sure that this variable is displayed in the page's HTML for tracking purposes.
Bloomreach supports widgets on mobile devices only if your mobile URL structure is the same as the structure for your desktop URLs. API responses can return relative URLs to support mobile versions. You can apply regular mobile styling to render the response.
Styling
You need to parse the response and place each widget in an appropriate location on the page. You can style your related categories, related items, and related products widgets by entering styles in your global CSS file.
The related products widget needs a lead-in or snippet of the product description with the rest of description in a quick view popup. Use one of the following techniques:
- Recommended method: Add the CSS and JavaScript snippets to the widget API response for popup functionality.
- Alternative method: Put the snippets in your own CSS and JavaScript files, and ensure that these files appear on the pages that contain the related products widget.
Caching
You can cache widget API responses. Set the cache to expire within a period of 24 hours maximum to ensure that the data is current.
Web crawling
Don't cache widget API responses for search engine bot traffic. Bloomreach needs to see all crawling activity on your site.