Thematic API (HTML)

Integration steps

The Bloomreach integration team meets with you to configure your Thematic Pages. Here are the essential steps that you follow with Bloomreach's guidance:

1. Define the URL structure for your Thematic Pages.

2. Determine how to handle different user agents, such as those for mobile devices and desktops.

3. Create a new page template.

4. Add a Thematic API call to the new page template. Here's how:

   4.1. Make a server-side API call to the Bloomreach Organic Thematic servers.

   4.2. Extract the header widget and Thematic body from the API response.

   4.3. Insert HTML markup in your page template.

5. Deploy your thematic XML sitemap.

Thematic integration checklist

• Verify that the page name extraction from the incoming URL is correct.
• Verify that API requests are formed correctly and that all the required parameters and values are populated.
• Verify that the raw API calls return valid HTML for a set of example pages.
• Verify that a call that returns empty HTML or a failure code causes the failover HTML to be populated.
• Verify that the header and body are returned and parsed correctly.
• Verify that the header section contents from the response are in the head section only one time.
• Verify that CSS, images, and JavaScript are in the correct directories and have valid permissions.
• Check the constructed thematic page and review it for errors, especially in its CSS and page structure.
• Verify that when an invalid thematic page is requested or the request times out, the page is redirected to the homepage with ?_thto=1 appended to the URL. For example: http://www.example.com/?_thto=1

Additional reading

• Thematic pages
• Deploy your thematic XML sitemap

Endpoints

• Production: Please reach out to your TPM/TC for your brSEO endpoint
• Staging: https://bsapi-test.brsrvr.com

Example request and response

GET https://example-0123-e.brcdn.com/fetch_thematic/
<Bloomreach Provided Account ID>/
jftyf00gh3pi0000j/
prod/
desktop/
v1/
white-dresses.html?
user_agent=Mozilla%2F5.0+%28compatible%3B+Googlebot%29
&url=http://www.example.com/popular/white-dresses-th.html

<!-- BEGIN HTML-HEADER -->
<title>Title of the Page</title>
<meta name="robots" content="noindex" />
<link rel="canonical" href="http://www.example.com/popular/white-dresses-th.html" />
<link rel="stylesheet" type="text/css" href="http://www.example.com/css/sample.css" />
<!-- END HTML-HEADER -->
<!-- BEGIN HTML-BODY -->
<div>
...
  <left column content>
  <product display similar to your category page display>
...
</div>
<!-- END HTML-BODY -->

📘

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 with Zero products

If you receive an API response and the number of products that match the theme is 0, you will have to set up behavior so that the page triggers a timeout.

Response processing

Bloomreach examines metrics like bounce rates and conversion rates to determine how well a page performs. If a page has suboptimal performance, then Bloomreach applies noindex meta tags. Therefore, the whole HTML header section from the response needs to be inserted into the HTML header of the page even if your page already has these same HTML elements. Replace the contents, don’t duplicate them.

Don’t hardcode noindex meta tags; consume what is sent in the response.

Encoding

The thematic search API response is Unicode UTF-8 encoded. If your site doesn’t interpret the response accordingly, then strange characters appear in the browser when the response is processed.

Caching

Never cache 4xx nor 5xx responses to your thematic API requests.

To ensure the best personalization experience for your site's users, we recommend that you don't cache thematic API responses. If necessary, you can cache success (2xx) responses, but never cache 4xx nor 5xx responses.

If you must cache your 2xx responses, then we recommend that you set the cache to expire in one hour. The maximum period is 24 hours to ensure that the data is current.

Timeouts

We recommend that you set the timeout for your thematic pages to 2 seconds.

If there's a timeout during a thematic page load, then we recommend that you redirect your customer with a HTTP 302 response code to your site's home page. Append this specific tracking parameter redirected the URL: ?_thto=1. This parameter serves a few purposes:

It ensures that your customers always receive a page load.

It collects data to assist Bloomreach in troubleshooting timeouts.

For example, let’s say that the following page encounters a timeout error when loading:

http://www.example.com/shop/gorgeous-red-cocktail-dresses

Then the site redirects the customer to the home page with a 302 response code, and uses the following URL:

http://www.example.com/?_thto=1

Your Bloomreach representative can work with you to determine the ideal timeout setting for your requirements.