HomeEngagementContentDiscoveryOther resources
API reference

Widget API

Related categories, related items, and related products widgets appear on your site to enhance discoverability and user value. With a single request, the widget API optimizes your link structure and page content by populating the content in your related categories, related items, and related products widgets.

Integration steps

Here are the essential Widget integration steps that you follow with Bloomreach's guidance:

  1. Create mockups to demonstrate the location and appearance of the Widgets. Bloomreach can provide best practice guidance on good locations and appearance for these Widgets.
  2. Develop CSS and JavaScript to control how the Widgets function and how they're styled.
  3. Add a Widget API call to all of the pages that you selected during integration kickoff.
  4. Make a server-side API call to the BR Organic Widget servers. This call extracts related categories, related items and related products from the HTML response, then inserts HTML markup in the appropriate locations.

🚧

Widget API calls are always server-side calls

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 for optimal search engine experience. Major search engines don't understand or value JavaScript and AJAX content as highly as HTML content and links.

Confirm that your widget data is in your browser's page source view, not in the element inspection.

Widget integration checklist

  • Verify that widget data is visible on both mobile and desktop pages when crawled by mobile search engine bots and users can see the widgets when they access these pages.
  • Verify that API requests are formed correctly, and all the required parameters and values populated. Look especially at the following items:
    • The url parameter value is the same as the URL in your customers’ browsers. Don’t use an internal, rewritten URL.
    • The ptype and user_agent parameter values are accurate. Don’t leave them empty.
  • Verify that the widgets appear correctly with valid HTML on each type of page where you expect them to appear.
  • Verify that links in the widgets point to valid pages, and that these pages themselves display the correct widgets.
  • Verify that widget data is visible on all integrated pages (primarily category and product pages) when crawled by search engine bots and users can see the widgets when they access these pages.
    • Widget data must appear in page source code.
  • Test that timeouts and lookup failures for remote API calls omit the widget.