Parameters for the JFY API - Bloomreach Experience - Open Source CMS

Parameters for the JFY API

Are you integrating your native mobile app (or other non-JS environment) with Bloomreach?

Some of the parameters in your API requests for native mobile apps or non-JS environment need different values from those for your site:

  • _br_uid_2: The value should be the same as described on the Cookie page. Generate a br_uid_2 for your app user and store it in the app permanently if a br_uid_2 does not exist. This br_uid_2 should be used on the corresponding API calls for the app. If the user is on iPhone and resets their IDFA, or if the user is on an Android device and resets their advertising settings: the br_uid_2 should be erased and regenerated the next time the app is set.
  • ref_url: Leave your ref_url parameters empty.
  • url: Use a dummy value for your url parameters, such as exampledomain.app.

Quick reference: request parameters

This table provides a list of each parameter and a description. A yes flag in the Required column indicates that the parameter is required for all JFY calls, not some.

Parameter Name

Required

Type

Description

Example

account_id yes integer The Bloomreach-provided ID of the account sending the request.  
auth_key yes string The Bloomreach-provided authentication key for the account sending the request. You must pass this parameter, but if your integration is client-side, then you can send it empty. jazzhands
_br_uid_2 yes string

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.

Don't percent encode this parameter.

uid=7797686432023:v=11.5:ts=1428617911187:hc=55

content_type no string (enum)

Specifies the type of content to return in the response. You can use one or more of the following values. If you use multiple values, then enter the values as a comma-separated list.

  • jfy (default)
  • dynamic_categories
  • recommendation
jfy,dynamic_categories,recommendation
domain_key yes string The Bloomreach-provided ID of the domain receiving the request. example_com
fl yes string

The fields returned with the JFY results, such as the name of products and prices. This value must be a comma-separated list. You must include the pid attribute in your fl parameter value. You can include other attributes from your product feed.

pid,title,brand,url
request_id yes string A random ID that enables click-tracking. Use 12 or 13 digits. 1597706996836
request_type yes string (enum)

The request type. Use jfyfor an ordered list of product customized according to the customer’s previous search behavior .

jfy
user_id yes string The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. 00000

view_id

no string A unique identifier for a view of the product catalog. Use a string that identifies the specific site catalog view for your customer. k-3

 

Detailed reference: request parameters

Some of the request parameters need a little more explanation than others. You can find this extra information here.

domain_key parameter

The Bloomreach-provided ID of the domain receiving the request. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.

fl parameter

The fl parameter is a comma-separated list of fields returned with JFY results, such as the name of products and prices. The following items are supported attributes. You can use other attributes, but attribute not in this list double the latency of the request.

  • thumb_image

  • title

  • url

  • brand

  • pid

  • category_id

  • sale_price

  • sale_price_typ

  • price

request_id parameter

The request_id parameter value is a random 12 or 13-digit ID that you supply to enable click-tracking. Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter  test  as your value for each instance of the request_id parameter without triggering an error message. However, if you don't use a unique value, then Bloomreach can't help you with potential problems you might experience while using the API.

request_type parameter

The request_type parameter indicates the type of search request that you're sending. You can use one of the following values:

  • jfy – (Just For You) an ordered list of product customized according to the customer’s previous search behavior

  • mlt – (More Like This) an ordered list of similar products

  • search – an ordered list of products for an input keyword or category query

  • suggest – a list of suggestions for an input string or query. For example, &q=sh might return shoes, women shoes, men shoes and black shoes.

user_id parameter

The user_id parameter is a universal customer ID of a user. The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Commerce Search and Categories recognizes users in a way that's aligned with your system. Use an anonymous string. Don't use email or other personally identifiable information. If you do not track users this way, then omit this field.

view_id parameter

The view_id parameter is a unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views.

You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog. For example, Abacus Thinking sells different academic products to different grade levels. A first grade teacher looks in their Kindergarten through Grade 3 catalog, which Abacus Thinking assigns the ID, k-3:

&view_id=k-3

Consistent, valid values 
Your view_id values must be the same in your API, pixel, and product catalog. If Abacus Thinking assigns the value, kindergarten-3rd, to the view_id parameter in their product feed, then the API value, k-3, doesn't match any catalog view.

Using * query
When you use the query '*' as 'q=*' in the API request, the latency of the response will vary depending on your catalog size and it may not adhere to the Bloomreach's standard SLA. Further, please note that except for include/exclude operation, other merchandising operations such as boost/bury or slots do not work on * query parameters.

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?