Just For You API (JFY) [deprecated]

🚧

The Just For You API is now part of the Recommendations and Pathways product and is no longer available for new integrations.

Just For You (JFY) is a Bloomreach Search and Merchandising feature. JFY includes the following personalizations:

  • Product Recommendations is a service that displays product recommendations for customers based on their browsing history. For example, if you have a customer who looks at very high heels, then you might suggest shoes with stiletto heels and shoes with four or five-inch heels.

  • Dynamic Categories is a service that displays recommended categories with sample products based on customers' browsing patterns. For example, if a customer browses several Louboutin slingback heels, then Dynamic Categories might suggest Shoes by Christian Louboutinor Evening Wear Shoes by Christian Louboutin, and display products matching those categories.

Endpoints

Production: https://core.dxpapi.com/api/v1/core/?
Staging: https://staging-core.dxpapi.com/api/v1/core/?

Example request and response

GET https://staging-core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=2779692816548
&_br_uid_2=uid%3D9683404349848%3A_uid%3D1060194806196%3Av%3D11.5%3Ats%3D1366069652967%3Ahc%3D109
&url=http://www.example.com/index.html?JFY
&ref_url=http://www.example.com/home
&request_type=jfy
&content_type=jfy,dynamic_categories
&fl=thumb_image,url,title,brand,pid,sale_price,sale_price_type,price
{
 "dynamic_cats_response": {
     "title":"dynamic_cats"
      "docs": [ // list of suggestions
            { // suggestion 1
             "docs": [ // list of products in suggestion 1
                 {
                  title: "example product",
                  price: 34.9,
                  url: "http://www.example.com/91000048803",
                  pid: "91000048803",
                  thumb_image:"http://example/6838/1000048803-930-MAIN-170x269.jpg",
                  sale_price: 15,
                  sale_price_type: "",
                  brand: "Almost Famous"
               },
               {
                  // second product in suggestion 1
               },],
             "master_cat": "name of master category",
             "title": product by almost famous
            },
            {
             //suggestion 2
             .....
            }
       ] // end of list of all suggestions
    "personalized result": "true"
  },
  
 "response": { // jfy response (Recently browsed across devices)
       "docs": [
           {
               "thumb_image": "http://www.example.com/productpics/thumb/screen.jpg",
               "title": "Samsung Galaxy Anti-Glare Screen Protector Film",
               "url": "http://www.example.com/p-166880",
               "brand": "Samsung",
               "pid": "166880",
               "sale_price": 7.99,
               "sale_price_type": "",
               "price": 7.99
           },
           {
              // product 2
           },
           {
              // Product 3
           }
       ],
       "title": "jfy"
   }
  "personalized result": "true"
}

❗️

API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.

Suggest categories

The Dynamic Categories service can suggest up to five Dynamic Categories. Each of these categories contains as many as 30 products with ranking optimized by Commerce Search and Categories based on various signals such as product generated revenue, conversions, views, and others.

Dynamic Categories are derived by examining the user's browsing history for product categories, brands, and on-sale statuses (boolean). The tuples (category, brand, sale) with the highest number of user activities become the user's personalized Dynamic Categories. These categories are tuned to user activities. The recommended categories and products are sensitive to changes in the category tree, product availability, price, and product performance. As the user browses more products, the recommendations become richer and more relevant.

Dynamic Categories are stored in dynamic_cats_response.docs.

You can specify excluded categories from Dynamic Categories. For example, you might decide to exclude sexual wellness categories from Dynamic Categories. Putting these categories on a blocklist prevents them from being automatically suggested when a user browses for other drugstore items. To block items from Product Recommendations, you need to contact your Bloomreach Technical Manager.

Suggest products

JFY begins generating personalized content after a user does three qualified activities, such as opening a product page. The Product Recommendations service can suggest as many as 20 products. These suggestions are based on the user's browsing history. The service compares the user's history with that of other users, identifying products with similar browsing patterns from similar users. As the browses more products, the recommendations are automatically updated. The more the user browses, the more refined the recommendations become.

The example response uses JSON output with JFY plus dynamic_cats_reponse. The user browsed at least three products, which is the threshold for showing Product Recommendations.

Product Recommendations are stored in response.docs.

What do JFY widgets display for new site visitors?

JFY widgets personalize suggestions and recommendations based on individual site visitor activity. If Bloomreach doesn't have enough information about a site visitor to generate personalized suggestions and recommendation, then your JFY widgets display bestseller products. For information about deploying the bestseller API on your site, see Bestseller API.

How do I check the quality of my JFY recommendations?

Here's how you can QA your JFY widgets:

  1. Open your site
    For best results, open your site in an incognito window. This way, you can be sure that your results are due to your activities during your test rather than prior activities.

  2. Open a page that displays a JFY widget
    Let's call this page your test page. Observe the products in the widgets. You're going to compare these products with the products displayed at the end of the test.

  3. Run a few searches and open at least five product pages per search
    This step simulates site visitor behavior so that Bloomreach can personalize the quality of results to individual visitors on your site.

  4. Return to your test page
    That's the page where you first noted the product recommendations in the JFY widget. Observe the set of products in the JFY widget. You're checking to see that the product recommendations are changed according to the search behavior you simulated during this test.

If your JFY widgets are still not displaying recommendations that are influenced by your activities, then contact your Bloomreach representative for help.

Native mobile app and non-JS integration

API requests for native mobile apps or non-JS environments need different values for some parameters:

  • _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.
Language
Click Try It! to start a request and see the response here!