Build an HTML thematic results page - Bloomreach Experience - Open Source CMS

Build an HTML thematic results page

Getting thematic search results

This page shows you an example request and response that can help you form your own thematic API calls for your site. If you need more information about thematic parameters, then take a look at the quick reference table, which describes the parameters and provides example values.

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.

Form of a thematic call for HTML results

GET http://<thematic_host>.brcdn.com/fetch_thematic/
<acct_id>/
<acct_auth>/
<environment>/
<device_type>/
<response_version>/
<page_name>.html?
user_agent=<user_agent>
&url=<url>

Tip

Add the following header to your request so that you receive a compressed response: Accept-Encoding: gzip, deflate. 

If you are a Demandware Cartidge user, then you don't need to add this header.

Tip

You can escape non-alphanumeric characters in your parameter values, using URL percent-encoding conventions.

Here's what the call looks like with sample data:

Example thematic search request

GET http://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

Here are the example values for the call:

  • example-0123-e is the host
  • <Bloomreach Provided Account ID> is the account ID
  • jftyf20gh3pi0273j is the authentication key
  • prod is the environment
  • desktop is the device type
  • v1 is the response version
  • white-dresses is the page name
  • Mozilla%2F5.0+%28compatible%3B+Googlebot%29 is the user agent
  • http://www.example.com/popular/white-dresses-th.html is the URL

Escape characters and encoding

You can escape non-alphanumeric characters in your parameter values, using URL percent-encoding conventions.

Values for query parameters that have multiple words can use URL percent-encoded spaces (%20) between the words. For example:

Character

Escape

/ %2F
( %28
; %3B
) %29

q and fq parameter values with %20 encoding

&q=lace%20dresses
&fq=color:"light%20blue"

Here's another example, this time with several different escape characters for the  user_agent  parameter:

user_agent parameter value with multiple escape characters

?user_agent=Mozilla%2F5.0+%28compatible%3B+Googlebot%29

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:

Escape double quotes

&fq=size:"8.5\" by 11\" "

Example truncated response

Bloomreach returns styled HTML 

in response to the request. The response consists of a header and a body of valid HTML that you need to parse and put into your body content.

The example request’s corresponding response looks like this:

Response snippet

<!-- 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 -->
Tip 
The response is gzip compressed. You need to uncompress the response to use the contents. If you are a Demandware Cartidge user, then your response is not compressed.

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

Do not cache client (4xx) nor server (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 TPM can work with you to determine the ideal timeout setting for your requirements.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?