The Bazaarvoice Personalization Data SDK provides a programming interface for clients to access the BV Personalization API(s) with minimal required configuration. To learn more, go to the Personalization Data SDK documentation home page.

Contents

(+ show- hide)

This section demonstrates obtaining recommendations data for a given BV ID. JSON data is returned. A callback function should be defined to handle data that is returned. The BV Loader must be present when using the getRecommendations() function.

getRecommendations()

This basic example uses the SDK to request product recommendations. The default type 'product' is inferred as well as the default limit of 10.

Products

      bvAPI.getRecommendations({
        slot: 'slot1',
        category: '255',
        pageType: 'home'
      });
    

This basic example uses the SDK to request product categories.

Categories

      bvAPI.getRecommendations({
        slot: 'slot2',
        type: 'category',
        category: '255',
        limit: 5,
        pageType: 'home'
      });
    

Even though the hosted display is not used, a slot identifier must be included.

Arguments

Name Type Default Description Priority
slot String N/A The identifier of the HTML container element where the personalized product recommendations are inserted. The slot identifier is used for analytics tracking and is required. Required
type String 'product' Accepted values are 'product' and 'category'. Recommended
category String N/A Prefers products in this category. This is the category external ID as provided in the catalog feed. Recommended
limit int 10 The number of elements (products or categories) in the response. Recommended
pageType String N/A Metadata for the type of the HTML page the recommendations are presented. Accepted values are 'home', 'category', 'product', 'cart', 'thankyou' and 'search'. Recommended

Response format

This sample response is from a request for product personalization data:

    {
      "client": "some_client",
      "product": "abc123",
      "name": "WOMENS SHIRT S/L SOLID COTTON SHARK pattern",
      "image_url": "https://www.some_client.com/images/abc123.png",
      "product_page_url": "https://www.some_client.com/womens_category/shirts_and_tops/product/abc123.jsp",
      "num_reviews": 1 // (Number) Number of Reviews,
      "avg_rating": 5.0 // (Number) Average Star Rating
    }
    

This sample response is from a request for category data:

    {
      "client": "some_client",
      "category": "abc12",
      "name": "WOMENS SHIRTS",
      "url": "https://www.some_client.com/womens_category/shirts_and_tops/sleeveless.jsp"
    }
    {
      "client": "some_client",
      "category": "abc1234",
      "name": "WOMENS PANTS",
      "url": "https://www.some_client.com/womens_category/pants/denim.jsp"
    },
    {
      "client": "some_client",
      "category": "def123",
      "name": "MENS SHIRTS",
      "url": "https://www.some_client.com/mens_category/shirts_and_tops/linen.jsp"
    },
    {
      "client": "some_client",
      "category": "def1234",
      "name": "MENS PANTS",
      "url": "https://www.some_client.com/mens_category/skirts/capri.jsp"
    }

    

Response elements

Name Description
client
Client name.
product
Bazaarvoice product externalId as specified in the catalog feed.
name
Product name as specified in the catalog feed.
image_url
Product image URL as specified in the catalog feed.
product_page_url
Product page URL as specified in the catalog feed.
num_reviews
Number of reviews.
avg_rating
Average product rating.
category
Category external ID as specified in the catalog feed.
url
URL to the category page as specified in the catalog feed.

Usage

Execute getRecommendations() when the API is ready. Error handling is also a good idea.

      <html>
        <head>

            <script src="https://apps.bazaarvoice.com/deployments/{client_name}/{deployment_zone}/{environment}/en_US/bv.js" async></script>
        </head>
        <body>
        <script>
            (function () {
                // Define global callback to be triggered when BV is available.
                window.bvCallback = function (BV) {
                    BV.api.ready().then(bvAPIReady).catch(recosError);
                };

                // This basic example uses the SDK to request product recommendations,
                // then renders the product images in order.
                function bvAPIReady (bvAPI) {
                    bvAPI.getRecommendations({
                        slot: 'slot1',
                        pageType: 'home'
                    }).then(renderProducts).catch(recosError);

                    bvAPI.getRecommendations({
                        slot: 'slot2',
                        category: '255',
                        limit: 5,
                        pageType: 'home'
                    }).then(renderProducts).catch(recosError);
                }

                function renderProducts (result) {
                    const recos = result.recommendations;
                    const slot = result.slot;
                    console.log(result);
                    recos.forEach(function (recommendation) {
                        const div = document.createElement('div');
                        const img = document.createElement('img');
                        img.src = recommendation.image_url;
                        div.setAttribute('data-bv-product-id', recommendation.product);
                        div.appendChild(img);
                        slot.appendChild(div);
                    });
                }

                function recosError (err) {
                    console.error(err);
                }
            })();
        </script>

        
        <h2>Recommendations Slot 1</h2>
        <div data-bv-p13n-slot="slot1"></div>

        <h2 style="margin-top: 20px">Scroll down...</h2>

        
        <h2 style="margin-top: 20px;">Recommendations Slot 2</h2>
        <div data-bv-p13n-slot="slot2"></div>
        </body>
      </html>

    
You must include the data-bv-product-id attribute with value of ProductId on the individual item container(s) when rendering the HTML elements. This is used for analytics purposes. See the highlighted line in the code sample above.

Error codes

Error codes are returned in the console.

Value Description
Unable to locate Personalization Slot

The slot parameter was not found in the HTML DOM

Uncaught Bazaarvoice is not configured for the domain {some domain}

The domain where the code is executing is not whitelisted. Please contact us.