Deprecated Widget API Integration.
The following is an old integration guide for Organic Widgets used by customers who integrated before April 2018. It contains integration details for Related Searches and Related Products. It is to be used for reference purposes ONLY and is no longer the suggested integration for Organic Widgets. Please refer to Widget API for the most up to date details on integrating the Organic Widgets which include how to integrate Related Categories, Related Items and Related Products.
What are related searches and related products widgets?
Related searches and related products are widgets that you place on your mobile and desktop sites to enhance discoverability and user value. The widget for related searches optimizes your link structure, and the widget for related products optimizes your page content.
Text on product results is usually in a form like JavaScript that isn't always readable by search engine bots. When a customer views your site, the widget API provides data to populate the related searches and related products widgets on the page. Each link in the related searches widget is highly relevant both to the page it's on and the page it's pointing to. These links create a relationship from one page to the next, assisting users and search engines to find new relevant pages. Each product in the related products widget includes a picture, title, and a lead-in snippet with a view more link to expose a popup of the description of the product.
The title and description of related products are readable by search bots, increasing the likelihood of discovery by bots. The links for related searches flatten your site's hierarchy for bots, making it easier for them to crawl your site.
Here are some of the methods we use to populate the content of your related searches and related products widgets:
- Examine relationships between products and categories on your site.
- Analyze your product attributes to link similarly patterned items together.
You need just one widget API call for both related searches and related products.
Related searches
The widget for related searches adds relevant links to your category and product pages, flattening the structure of your site. This widget helps web crawlers easily discover other related pages from this single page as well as pass on the strength or authority from this single page to these other pages, helping them to rank and receive more organic search traffic from search engines.
This widget is particularly helpful to users who don't immediately find exactly what they're looking for on a particular page. For example, a customer named Lucia searches your site with the query, white dresses. The list of related searches on the category page or product page might include wedding gowns, summer dresses, and lace dresses. Lucia can click these links to find more pages that are highly relevant to her search for the perfect white dress.
The number of searches that you can have in your related searches widget is fixed at six. Bloomreach always tries to display the maximum number of links in the related searches widget. However, the widget shows fewer links if we can't find relevant product pages to link to, or if the products in those linked pages go out of stock.
Display requirements for related searches widgets
For each link within related searches, the following requirements apply:
- Clearly display the entire link or anchor text. Do not truncate any of the link or anchor text with ellipses. For example: blue lace dres...
- Show all the links that are in the widget and do not truncate the list. For example, don't show three links upon page load followed by a link or button to show more or show fewer links.
Related products
The widget for related products adds products on relevant category and product pages. The related products widget leverages your site’s product content, adding it to relevant pages to enrich the content on those pages with additional and unique content. Adding this content helps these pages rank in additional searches when customers make queries on search engines.
For example, Dresses by Colette sells a pink dress called Sweet in Pink on its product page. This product appears on multiple category and product pages in the related products widget. The content for this product is served in HTML and is readable by search engines. As a result, when Lucia uses a search engine to find a hi-lo pink dress, chances are increased that Dresses by Colette's Sweet in Pink product appears in her search results.
The default number of products you can have in your related products widgets is four. Let your Bloomreach TPM know if you want to display more than four products. Bloomreach always tries to display the maximum number of products in the related products widget. However, the widget shows fewer products if we can't find relevant products that match the content of the page, or if products in the widget go out of stock.
Upon page load of every page, the related products widget must be visible to site visitors and search engine bots. This widget contains individual items that each include information like a product title, product image, preview of the product description, and a quickview link. When a site visitor clicks the quickview link, a popup HTML lightbox displays detailed content, including the product title, product image, and an expanded product description.
Location and appearance of widgets
During the integration process, the Bloomreach integration team meets with you to establish the location and appearance of your related searches and related products widgets on your product, category, and mobile pages.
Category pages
The recommended placement for the related searches widget is in the left navigation area. The recommended placement for the related products widget is below the product grid
Example request and response
GET https://example.brsrvr.com/v2/fetch_widget
?url=http%3A//www.example.com/product%3Fid%3D999
&acct_id=<Bloomreach Provided Account ID>
&acct_auth=als39h0g93jfd03vnxop
&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
Receive a compressed response
The response is gzip compressed by default. You need to uncompress the response to use the contents.
If you want to receive a compressed response, add the following header to your request:
Accept-Encoding: gzip, deflate.
If you are a Demandware Cartridge user, then you don't need to add this header.
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 searches 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 searches 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.