DCC Signed Events

DCC events are triggered when a consumer visits a PDP on a client's website. This event sends product data to Bazaarvoice which, due to the PDP’s publicly viewable code, becomes vulnerable to copying or interception.

Traditional DCC includes an event callback feature that triggers an AWS Bazaarvoice component which signals the PDP. Once the callback event and product data have reached Bazaarvoice, the AWS component validates that the data received matches the PDP data. This regularly fails due to IP blocking, timeouts, or redirects which prevent the data validation step from completing.

DCC Signed Events, however, digitally signs events using a JSON Web Token (JWT). This JWT is sent alongside the product data. In configuration, a public key is recorded which is used to verify this data on Bazaarvoice servers. This removes the need for a callback and reduces the potential of failed product updates in the catalog.

Prerequisites

Contact Bazaarvoice Client Care to enable DCC before attempting to provide product catalog data using the following steps.

Setup DCC Signed Events

Perform the following steps to set up DCC Signed Events.

Step 1: Generate keys

To generate the required keys, run the following commands on OSX/linux:

ssh-keygen -t rsa -b 2048 -m PEM -f bvdcc.key
openssl rsa -in bvdcc.key -pubout -outform PEM -out bvdcc.key.pub
Note: The RSA encoding element must be used for Bazaarvoice to accept your code.

These commands will generate the following two files:

  • bvdcc.key —The client’s private key. This should only be used for signing events on the client’s server.
  • Caution: It should be stored securely and never shared.
  • bvdcc.key.pub — The client’s public key. This does not need to be stored securely. It should be added under the DCC key setting in configuration:

Step 2: Implementing server-side data

The recommended approach will be to:

  1. Modify the product data javascript so it is in the correct format for DCC.
  2. Sign product data using the JWT token by using the following code as a template for signing events using a JWT with a node library .
  3. Note: The key part is the signCatalogUpdate function which will return an array of strings.
    Installing library;
    npm install --save jsonwebtoken
    
    Usage;
    /*
    Resources:
    jsonwebtoken Module: https://www.npmjs.com/package/jsonwebtoken
    fs Module: https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options
    JSON.stringify method: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
    */
    
     
    //SERVER SIDE PSEUDO CODE
     
     
    //Import required modules (jsonwebtoken and fs)
    const jwt = require('jsonwebtoken');
    const fs = require('fs');
     
    //Assigns previously generated (and secretly stored) private key to a variable
    const privateKey = fs.readFileSync('PATH TO PRIVATE KEY GOES HERE');
      
    const locale = 'en_US';
    const products = [
    {productId":"MH02",
                  "inactive": false,
    "productName":"Teton Pullover Hoodie",
                "productDescription":"The Teton Hoodie Description",
                "productImageURL":"https:\\mywebsite.com\pub\media\catalog\product\mh02-black_main.jpg",
                "productPageURL":"https:\\mywebsite.com\teton-pullover-hoodie.html",           
                "brandName":"MyBrand",
                "categoryPath" : [
                    {
                       "id" : "123",
                       "Name" : "Parent Category Name"
                    },
                    {
                      "id" : "123-1",
                      "Name" : "Mens"
                    },
                    {
                      "id" : "123-1-9",
                      "Name" : "Pants"
                    }],
    
                "upcs":["724742001735","724742006907","077320775406","077320775307"],
                "manufacturerPartNumbers":["mpn1","mpn2","mpn3","mpn4","mpn5"],
                "eans":["0724742001735","0724742006907","0077320775406","0077320775307"],
                "isbns":["9781891830754","9781603090506","9781891830716","9781603090254"],
                "modelNumbers":["model1","model2","model3","model4"],
                "family": "F02",
                "price": "12.99",
                "currencyCode": "USD",
                "color": "red",
                "size": "large",
                "material": "nylon",
                "availability": true
    
              },
    //Example of custom attributes
                "customAttributes": [
                    {
                      "id": "CustomAttributeId123",
                      "value": "Custom attribute value 1"
                    },
                    {
                      "id": "CustomAttributeId456",
                      "value": "Custom attribute value 2",
                    }],
    
    //Example of adding multi-products into a single call
        {
            "productId": "1_Black",
            "productName": "Hummingbird printed t-shirt Black",
            "productPageURL": "http://dcc-test-site.qa.us-east-1.nexus.bazaarvoice.com/men/1-3-hummingbird-printed-t-shirt-6419892469002.html",
        },
    ];
      
    //Passes catalog data and privateKey into the token; encoded as RS256
    function signCatalogUpdate(products, privateKey) {
        return products.map(product => jwt.sign({ locale, catalogProducts: [ product ] }, privateKey, { algorithm: 'RS256' }));
    }
     
    //Assigns the returned output from the signCatalogUpdate function to a variable which is then visible on front-end
    const bvDCC = signCatalogUpdate(products, privateKey);
     
    //Outputs DCC product data in a console log, and enters 2 spaces for any NULL values 
    console.log(JSON.stringify(bvDCC, null, 2));
    
  4. Expose the signed data to the front-end javascript using an API.
  5. Expose your code to the front-end as window.dccSignedTokens.
    Note: To view a code example, visit this site and access the developer window by right-clicking and selecting ‘Inspect’.

Step 3: Implementing front-end data

Replace the existing “CatalogUpdate” DCC javascript on the PDP with one of the following implementations:

Multi-product PDP:

<script async type="text/javascript">
window.bvCallback = function (BV) {
  // Use a loop for multiple products
  for(var i=0, len=window.dccSignedTokens; i < len; ++i){
    BV.pixel.trackEvent("CatalogUpdate", {
      type: 'Product',
      token: window.dccSignedTokens[i]
    });
  }
};
</script>

Single-product PDP:

<script async type="text/javascript">
window.bvCallback = function (BV) {
  BV.pixel.trackEvent("CatalogUpdate", {
    type: 'Product',
    token: window.dccSignedToken
  });
};
</script>
Caution: Make sure that the value assigned to “token” is the signed version of the “catalogProducts” data, and matches the validation outlined in the DCC data attributes section

DCC data attributes

The following table describes data attributes used in DCC JavaScript.

Attribute Value Required
productId

Unique product ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If the external product ID contains an invalid character, replace it with an alternate character, such as an underscore. The ID is case insensitive, so you cannot use IDs that match except for case.

This format is used in the data feed only and is not visible to end users.

Type: string

Yes
locale

Specifies the desired locale. If this attribute is not provided, the locale of the BV loader reference is used.

Type: string

Yes
productName

Name of the product, which is visible to end users.

Type: string

Yes
productDescription

Description of the product. We recommend that product descriptions be at least three sentences or 300 characters long.

Type: string

No
productPageURL

Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. When specifying a URL, be aware of the following:

If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).

Type: URL

Yes
productImageURL

Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. When specifying a URL, be aware of the following:

If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).

Note: If Conversations is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

Type: URL

Yes
Color

Color of the product.

No; Recommended
Size

Size of the product.

No; Recommended
Material

Material of the product. For example, Steel, plastic, silk, etc.

No; Recommended
Currency

Currency of the product in each locale.

Note: Currency must be provided in the format ISO 4217N.

No; Recommended
Price

Price of the product.

No; Recommended
Availability

Indicates whether or not a product is available to purchase. It may be out of stock or out of season.

No; Recommended
brandId

Unique brand ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If a brand ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case.

Ensure the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.

Refer to the Brands section for details about how to collect Brand data using DCC.

Type: string

No
brandName

The name of the brand to which the product belongs. Refer to the Brands section for details about how to collect Brand data using DCC.

Type: string

No
categoryPath A list of categories ordered by hierarchy. Refer to the Categories section for details about how to collect Category data using DCC. No
family The product family name to which the product belongs. We recommend that you exclude special characters from product family names. Refer to this section for details about how to configure product families using DCC. No
upcs

Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. In an array, include each UPC you want to define, which can contain numerals only, with no letters or other characters. Remove spaces and hyphens because they disrupt syndication matching.

Note: Bazaarvoice does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored.

Type: array

No; syndication matching improves if you specify UPCs.
manufacturerPartNumbers

Manufacturer-specific part number. Part numbers can contain letters, numerals, and characters.

Type: array

No
eans

European Article Numbers (EAN), which is used worldwide for marking retail goods. An EAN must be a string of eight numerals or 13 numerals (no letters or other characters are allowed). Remove spaces and hyphens because they disrupt syndication matching.

Note: Bazaarvoice does not enforce length or numerical constraints on EANs. Values are validated during the catalog import process, however, and only valid values are stored.

Type: array

No; syndication matching improves if you specify EANs.
isbns

International Standard Book Number (ISBN), which is a 10- or 13-character value used predominantly for media products such as books, music, and videos. The last character provides a checksum that helps validate the product identifier. Most ISBNs are composed only of digits, except for some 10-character ISBN values that use an X for the checksum.

Type: array

No
modelNumbers

Unique referencing code that businesses use to identify a part that a particular industry uses. Each model number can contain letters, numerals, and other characters.

Type: array

No
inactive

Signals that the product is inactive. The default value is false. Refer to Control the active set of products for more details.

Type: boolean

No
customAttributeId

Enables you to define additional product-specific information for reporting. Specify an ID and value for each product attribute you want to define. Spaces are not permitted in the attribute ID.

Type: array

No. If included, you can specify an unlimited number of child elements.

Filter catalog data based on custom product attributes

To filter your product feed by custom product attributes, you must add them to your feed configuration. This lets you filter based on attributes in the content dashboards and reports in the Workbench. Custom product attributes give you a way to report on product-specific information; however, it does not provide multiple categories in a feed. For example, you could define a "region" attribute to report on hotels in a region of the country. Or, you could define a "department" attribute to track how products from various departments are being received by your customers.

Note: If you want to include custom product attributes in a text feed, contact Bazaarvoice Client Care for assistance.

The following video illustrates how to use custom product attributes.

Complete these steps to add a custom product attribute to your implementation and then enable custom product attributes in the Workbench:

  1. Include custom product attributes in the feed by adding the <Attributes> block to the <Products> element. Each <Attribute> element in the <Attributes> block identifies a custom attribute. Here is an example of three custom attributes:
    <Products>
    <Product> ... <Attributes> <Attribute id="CHANNEL_VISIBILITY">
    <Value>Any</Value>
    </Attribute>
    <Attribute id="SAP_STATUS">
    <Value>L</Value>
    </Attribute>
    <Attribute id="BUYING_NUMBER">
    <Value>Not_Available</Value>
    </Attribute>
    </Attributes> </Product>
    </Products>
  2. From the Workbench of your staging server, select Settings > Manage Applications.
    Note: You can create attributes on your production server, but you may want to test and preview this on the staging server first.
  3. From the Implementations section of the Site Manager page, edit the implementation that is deployed to the Main Site deployment zone.
    Note: Custom product attributes cannot be enabled in individual deployment zones. If they are not enabled in the Main Site deployment zone, they are not displayed in the Workbench.
  4. Select Getting Started > Technical Setup and then select the Product Feeds tab.
  5. In the Feed Attributes section at the bottom of the Product Feeds page, type an attribute name in the Custom Product Attributes field and then select Add. The attribute name must match the id attribute of the <Attribute> element in the product feed. Repeat this step for every attribute you want to add.

    This example shows attributes that match the IDs in the previous XML example:

You can use custom product attributes to filter content in Workbench analyst reports, dashboards, and other views.

Note: You cannot filter data based on custom product attributes in the Reports section of the Workbench. Viewing product attribute data is only supported on legacy dashboards.

For example, you can filter the Content > Manage Content : Ratings & Review view by selecting Product Attributes from the Product dropdown list. You can specify one or more attribute names, and only content that includes those attributes are displayed on the Manage Content: Ratings & Reviews page, like the following example illustrates.

Share reviews using product families

The product families feature in Conversations enables you to share UGC among multiple related products. By grouping products into families, you can display UGC written about one family member on the product display pages of all family members. Sharing reviews among product family members increases the following key performance indicators for your Bazaarvoice implementation:

  • Percentage of products with displayed reviews
  • Number of products with displayed reviews
  • Average reviews per product
  • Number of total displayed reviews

Types of product families

The type of product family that you use depends on how products differ:

  • Product variants — Products that are nearly identical to other products in terms of consumer experience, but they have different SKUs or part numbers. For example, products that come in different colors, different sizes, or are packaged in different weights or quantities may be variants of one another. Content from product variants is usually shared in all directions. All products in a given family display content that was written about the other family members.

    Creating a product family of product variants works best when each product variant is featured on its own product display page. If all product variants share the same page on your site, treating the variants as one product when integrating with Bazaarvoice may be simpler and more practical than setting up a product family for those products.

  • Product bundles — Groups of products sold together that otherwise may be sold individually. Content about product bundles is usually shared in one direction: from individual components to the product bundle. Typically, the product display page of a bundle displays all reviews written about the individual components. However, the product display page of each component shows reviews only about that component.

Configure product families

You can configure product families in your DCC JavaScript on product display pages, product feed, or through the Workbench. You can assign a product to one or more families at the same time using all of these methods.

Keep the following caveats in mind when configuring product families:

  • Product family configurations do not carry over between the staging and production environments.
  • Any changes you make to product families in the Workbench can be undone only through the Workbench.
  • Family definitions in the product feed do not override any family operations in the Workbench.
Note: Syndication ignores product family relationships. If you plan to or have implemented syndication, contact Bazaarvoice Client Care before configuring product families in your product feed.

Using DCC

There are two approaches for providing product family data using DCC:

  • Simple approach—Intended for the most common case where a given product should be a member of a single family, with reviews shared.
  • Complex approach—Intended for all other family scenarios, including products in multiple families.

Simple family approach

In your product display page's DCC JavaScript, you can include the attribute family. The value of family should be the ID of the product family to which you want to add a given product. Providing the family attribute results in the following:

  • The product will be added to the family with the ID specified.
  • The expand attribute will be set to True. This enables a product to display all content from other members of the family.
  • If the product already exists in any other families, the product will be removed from those families.

Example of providing a single family attribute:

...
        catalogProducts: [{
            "productId":"MH02",
            ...
            "family": "123",
            ...
        }]
      };
...

Complex family approach

To add a given product to multiple families or explicitly control each family definition, include the families array. It contains additional attributes (id, expand, members).

Example of providing a families attribute:

catalogProducts: [{
    "productId":"MH02",
    ...
    "families": [{
        "id": "123",
        "expand": true,
        "members": ["MH02","MH01","MH03"]
    }],
    ...
}]

Using the product feed

Bazaarvoice recommends you create product families through the product feed if you have a clear idea about which products can be grouped into families. Automating those relationships in the product feed is straightforward and faster than creating them using the Workbench.

You can configure product families in your product feed by including one or both of the following attributes:

  • BV_FE_FAMILY—Adds a product to a specific family.
  • BV_FE_EXPAND—Enables a product to display all content from other members of the family.
Tip: Bazaarvoice recommends that you do not use special characters, such as commas, in product family names.

In this XML example, all products in a family display content about all other members in the family.

<Product>
     <ExternalId>...</ExternalId>
     <Name>Green iPod Nano</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>iPod_Nanos</Value>
          </Attribute>
          <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:iPod_Nanos</Value>
          </Attribute>
     </Attributes>
</Product>
<Product>                 
     <ExternalId>...</ExternalId>
     <Name>Pink iPod Nano</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
       <Attribute id="BV_FE_FAMILY">
        <Value>iPod_Nanos</Value>
        </Attribute>
        <Attribute id="BV_FE_EXPAND">
             <Value>BV_FE_FAMILY:iPod_Nanos</Value>
       </Attribute>
     </Attributes>
</Product>

In the following XML example, the product bundle includes BV_FE_EXPAND, so all reviews about family components display on the bundle's page. However, BV_FE_EXPAND is omitted from the product <Attribute> definitions of the individual components to prevent reviews about the bundle from displaying on component pages.

<Product>
     <ExternalId>...</ExternalId>  
     <Name>Value Bundle</Name>   
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId>
     <CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>Value_Bundle</Value>
          </Attribute>
          <!-- Including BV_FE_EXPAND displays content from all components on the bundle page -->
          <Attribute id="BV_FE_EXPAND">
               <Value>BV_FE_FAMILY:Value_Bundle</Value>
          </Attribute>
     </Attributes>
</Product>
<Product>
     <ExternalId>...</ExternalId>
     <Name>Standalone Component</Name>
     <Description>...</Description>
     <BrandExternalId>...</BrandExternalId><CategoryExternalId>...</CategoryExternalId>
     <ProductPageUrl>...</ProductPageUrl>
     <ImageUrl>...</ImageUrl>
     <Attributes>
          <Attribute id="BV_FE_FAMILY">
               <Value>Value_Bundle</Value>
          </Attribute>
     </Attributes>
     <!-- Omitting BV_FE_EXPAND prevents content from the bundle from being displayed on the component page -->
</Product>

Using the Workbench

Use the Workbench to manually create families in the following situations:

  • You are not familiar with XML.
  • You are unable to work on the product feed.
  • You need to create a family whose UGC sharing relationships are not straightforward or possible to configure in the product feed.

    The following two examples describe scenarios in which a product family should be created using the Workbench.

    • A category manager for MP3 players wants to share reviews among all the colors of the 32 MB and 64 MB players. Setting up separate families for the 32 MB device and the 64 MB device is straightforward in the feed. However, because the 32 MB device and 64 MB device have different SKUs, combining them into one family using the feed might not be possible. The category manager should configure the family in the Workbench.
    • A personal-care brand manager wants to bundle lip balm and sunscreen for sale during the summer months. The brand manager wants to configure a product family containing the lip balm and sunscreen so that reviews about the individual family members will be shared on the product bundle's page. However, the lip balm and sunscreen do not have a common product feed element to link them together. The brand manager should configure the product family in the Workbench. When the season ends and the brand manager no longer wants to sell the products together, the manager can delete the product family bundle using the Workbench.

Complete the following steps to configure product families through the Workbench.

  1. Sign in to the Workbench and navigate to Content > Manage Families.
  2. Select Add New Family, and enter a name for the product family.
  3. Enter the Product ID, as listed in your XML product feed, for every product you want to add to the family, and select Add Product.
  4. Deselect Expand if you do not want the corresponding product to display content from family members.
  5. Select x to return to the Manage Families page.

Define a product category hierarchy

If you create an XML feed file, you can define product category hierarchy. You can associate each product with a specific category within the hierarchy using the <CategoryExternalId> element, and you can define a category's parent, thereby defining the category hierarchy, using the <ParentExternalId> element.

Be aware of the following if you are providing multiple feeds for your catalog data:

  • A product that appears in multiple feeds must be in the same category in all feeds. Therefore, if product A is in category X in Feed A, then product A cannot be in category Y in Feed B.
  • A category that is listed in multiple feeds must be in the same parent category in all feeds. Therefore, if category A is in parent category X in Feed A, then category A cannot be in parent category Y in Feed B.

The following XML file excerpt defines a <CategoryExternalId> for a category that is then reference by a <ParentExternalId> element.

<Categories>
   <Category>
      <ExternalId>food-1123</ExternalId>
       <Name>Food</Name>            <= no parent category; this is a top-level hierarchy element
         ...
   </Category>
   <Category>
      <ExternalId>fruit-1789</ExternalId>
      <Name>Fruit</Name>
      <ParentExternalId>food-1123</ParentExternalId>         <= "Fruit" category is a child of category “Food”
      ...
   </Category>
</Categories>
<Products>
   <Product>
      <ExternalId>123</ExternalId>
      <Name>Apple</Name>
      <CategoryExternalId>fruit-1789</CategoryExternalId>      <= belongs to category “Fruit”
      ...
   </Product>
   ...
</Products>

DCC Legacy

Note: DCC has recently been updated to DCC Signed Events which removes the need for a callback and reduces the potential of failed product updates in the catalog. Please refer to the DCC Signed Events section for information on implementation.

Step 1: Add the BV loader

The BV loader is a small, asynchronous JavaScript application that manages and displays configured features and UGC on your web pages. The BV loader will only download the required applications requested on the specific page.

To integrate the BV loader, add the following to your HTML inside the <head> of each PDP:

<!-- load BV loader -->
            <script async src="https://apps.bazaarvoice.com/deployments/<client_name>/<site_ID>/<environment>/<locale>/bv.js"></script>

where:

  • async—Downloads the BV loader asynchronously. This attribute is optional but recommended.
  • src—Specifies the path to the BV loader. Replace the following elements in your HTML:
    • <client_name>—The client name provided by Bazaarvoice. Be sure to use lowercase letters for the value.
    • <site_ID>—The ID of the deployment zone you want to use. This is set in the configuration in the Bazaarvoice Portal. The default deployment zone is "main_site". Check with your Bazaarvoice representative to ensure the correct ID, or select to the right of Main Site on the configuration page in the Bazaarvoice Portal.
    • <environment>—The deployment environment where you want to implement Bazaarvoice features. For a production environment, include production in the path. If you are referencing a staging environment, include staging in the path.
    • <locale>—The locale that is used by the implementation. For example, en_US for English.

Here is an example URL for Endurance Cycle's staging environment of the Main Site deployment zone:

https://apps.bazaarvoice.com/deployments/endurancecycles/main_site/staging/en_US/bv.js

Here is an example URL for Endurance Cycle's production environment of the implementation. The deployment zone (site ID) is named "mobile":

https://apps.bazaarvoice.com/deployments/endurancecycles/mobile/production/en_US/bv.js

        add-code-to-product-display-pages">Bazaarvoice-hosted display</a> or <a href="bvpixel.html#steps-to-implement-bv-pixel">BV Pixel</a>, do not add it again. Add the BV loader only once on each page.</div> <a id="add-dcc-javascript"></a>

Step 2: Add DCC JavaScript to product display pages

To collect catalog information from your product display pages, add the following JavaScript to each of your PDPs immediately before the closing </body> tag.

Tip: To make sure your JavaScript is valid, escape all string values to avoid special characters in fields such as productName.

Example JavaScript for product display page with one product

<script async type="text/javascript">
      window.bvDCC = {
        catalogData: {
         locale: "en_US",
         catalogProducts: [{
            "productId":"MH02",
            "productName":"Teton Pullover Hoodie",
            "productDescription":"The Teton Hoodie Description",
            "productImageURL":"https:\\mywebsite.com\pub\media\catalog\product\mh02-black_main.jpg",
            "productPageURL":"https:\\mywebsite.com\teton-pullover-hoodie.html",           
            "brandName":"MyBrand",
            "categoryPath" : [
                {
                   "id" : "123",
                   "Name" : "Parent Category Name"
                },
                {
                  "id" : "123-1",
                  "Name" : "Mens"
                },
                {
                  "id" : "123-1-9",
                  "Name" : "Pants"
                }],
            "upcs":["724742001735","724742006907","077320775406","077320775307"],
            "manufacturerPartNumbers":["mpn1","mpn2","mpn3","mpn4","mpn5"],
            "eans":["0724742001735","0724742006907","0077320775406","0077320775307"],
            "isbns":["9781891830754","9781603090506","9781891830716","9781603090254"],
            "modelNumbers":["model1","model2","model3","model4"],
            "family": "F02",
            "inactive": false,
            "price": "12.99",
            "currencyCode": "USD",
            "color": "red",
            "size": "large",
            "material": "nylon",
            "availability": true

}]
        }
      };

window.bvCallback = function (BV) {
          BV.pixel.trackEvent("CatalogUpdate", {
              type: 'Product',
              locale: window.bvDCC.catalogData.locale,
              catalogProducts: window.bvDCC.catalogData.catalogProducts
 
});
       }; 
</script>

Example JavaScript for product display page with multiple products

If you have a product display page that references multiple products (often variants in size, color, etc.), add JavaScript similar to the following example. The Bazaarvoice catalog requires IDs for each of these child products.

<script async type="text/javascript">
  window.bvDCC = {
        catalogData: {
         locale: "en_US",
         catalogProducts: [{
            "productId":"MH02",
            "productName":"Red Teton Pullover Hoodie",
            ...
          },
          {
            "productId":"MH03",
            "productName":"Blue Teton Pullover Hoodie",
            ...
          },
          {
            "productId":"MH04",
            "productName":"Green Teton Pullover Hoodie",
            ...
          }]
        }
      };

window.bvCallback = function (BV) {
         // Use a loop for multiple products
         for(var i=0; len=window.bvDCC.catalogData.catalogProducts.length; i < len; i++){ 
          BV.pixel.trackEvent("CatalogUpdate", {
            type: 'Product',
            locale: window.bvDCC.catalogData.locale,
            catalogProducts: [ window.bvDCC.catalogData.catalogProducts[i] ]
          });
        }
      };
  </script>

Example JavaScript for product display page for products with custom attributes

If you have products with attributes that are not included in our standard collection of DCC data attributes, you can still add them as custom attributes to your JavaScript as shown in the following example.

<script async type="text/javascript">
      window.bvDCC = {
        catalogData: {
         locale: "en_US",
         catalogProducts: [{
            "productId":"MH02",
            "productName":"Red Teton Pullover Hoodie",
            "productDescription":"The Teton Hoodie Description",
            "productImageURL":"https:\\mywebsite.com\pub\media\catalog\product\mh02-black_main.jpg",
            "productPageURL":"https:\\mywebsite.com\teton-pullover-hoodie.html",           
            "brandName":"MyBrand",
            "categoryPath" : [
                {
                   "id" : "123",
                   "Name" : "Parent Category Name"
                },
                {
                  "id" : "123-1",
                  "Name" : "Mens"
                },
                {
                  "id" : "123-1-9",
                  "Name" : "Pants"
                }],
            "customAttributes": [
                {
                  "id": "CustomAttributeId123",
                  "value": "Custom attribute value 1"
                },
                {
                  "id": "CustomAttributeId456",
                  "value": "Custom attribute value 2",
                }],
            "upcs":["724742001735","724742006907","077320775406","077320775307"],
            "manufacturerPartNumbers":["mpn1","mpn2","mpn3","mpn4","mpn5"],
            "eans":["0724742001735","0724742006907","0077320775406","0077320775307"],
            "isbns":["9781891830754","9781603090506","9781891830716","9781603090254"],
            "modelNumbers":["model1","model2","model3","model4"],
            // "family": "F02",
            "families": [{
                  "id": "123",
                  "expand": true,
                  "members": ["MH02", "MH01", "MH03"]
            }],
            "inactive": false,
            "price": "12.99",
            "currencyCode": "USD",
            "color": "red",
            "size": "large",
            "material": "nylon",
            "availability": true
          }]
        }    
      };
 
window.bvCallback = function (BV) {
          BV.pixel.trackEvent("CatalogUpdate", {
            type: 'Product',
            locale: window.bvDCC.catalogData.locale,
            catalogProducts: [ window.bvDCC.catalogData ]
          });
        }
</script>

DCC data attributes

The following table describes data attributes used in DCC JavaScript.

Attribute Value Required
productId

Unique product ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If the external product ID contains an invalid character, replace it with an alternate character, such as an underscore. The ID is case insensitive, so you cannot use IDs that match except for case.

This format is used in the data feed only and is not visible to end users.

Type: string

Yes
locale

Specifies the desired locale. If this attribute is not provided, the locale of the BV loader reference is used.

Type: string

Yes
productName

Name of the product, which is visible to end users.

Type: string

Yes
productDescription

Description of the product. We recommend that product descriptions be at least three sentences or 300 characters long.

Type: string

No
productPageURL

Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. When specifying a URL, be aware of the following:

If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).

Type: URL

Yes
productImageURL

Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. When specifying a URL, be aware of the following:

If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).

Note: If Conversations is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.

Type: URL

Yes
Color

Color of the product.

No; Recommended
Size

Size of the product.

No; Recommended
Material

Material of the product. For example, Steel, plastic, silk, etc.

No; Recommended
Currency

Currency of the product in each locale.

Note: Currency must be provided in the format ISO 4217N.

No; Recommended
Price

Price of the product.

No; Recommended
Availability

Indicates whether or not a product is available to purchase. It may be out of stock or out of season.

No; Recommended
brandId

Unique brand ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If a brand ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case.

Ensure the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.

Refer to the Brands section for details about how to collect Brand data using DCC.

Type: string

No
brandName

The name of the brand to which the product belongs. Refer to the Brands section for details about how to collect Brand data using DCC.

Type: string

No
categoryPath A list of categories ordered by hierarchy. Refer to the Categories section for details about how to collect Category data using DCC. No
family The product family name to which the product belongs. We recommend that you exclude special characters from product family names. Refer to this section for details about how to configure product families using DCC. No
upcs

Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. In an array, include each UPC you want to define, which can contain numerals only, with no letters or other characters. Remove spaces and hyphens because they disrupt syndication matching.

Note: Bazaarvoice does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored.

Type: array

No; syndication matching improves if you specify UPCs.
manufacturerPartNumbers

Manufacturer-specific part number. Part numbers can contain letters, numerals, and characters.

Type: array

No
eans

European Article Numbers (EAN), which is used worldwide for marking retail goods. An EAN must be a string of eight numerals or 13 numerals (no letters or other characters are allowed). Remove spaces and hyphens because they disrupt syndication matching.

Note: Bazaarvoice does not enforce length or numerical constraints on EANs. Values are validated during the catalog import process, however, and only valid values are stored.

Type: array

No; syndication matching improves if you specify EANs.
isbns

International Standard Book Number (ISBN), which is a 10- or 13-character value used predominantly for media products such as books, music, and videos. The last character provides a checksum that helps validate the product identifier. Most ISBNs are composed only of digits, except for some 10-character ISBN values that use an X for the checksum.

Type: array

No
modelNumbers

Unique referencing code that businesses use to identify a part that a particular industry uses. Each model number can contain letters, numerals, and other characters.

Type: array

No
inactive

Signals that the product is inactive. The default value is false. Refer to Control the active set of products for more details.

Type: boolean

No
customAttributeId

Enables you to define additional product-specific information for reporting. Specify an ID and value for each product attribute you want to define. Spaces are not permitted in the attribute ID.

Type: array

No. If included, you can specify an unlimited number of child elements.

Brands

A product can be associated with only one Brand entity in your product catalog. A Brand entity has a single unique brandId with localized brandName values (if provided in your catalog data). There are two ways to provide Brand data via DCC, depending on how many locales are specified in your implementation.

Single locale implementation

If your implementation only uses one locale, only brandName is required. Bazaarvoice will auto-generate brandId values using the brand name provided.

Note: You can provide your own brandId values if you have defined them already and want Bazaarvoice to use them in your product catalog instead.

Multi-locale implementation

If your implementation uses multiple locales, how you provide Brand data depends on whether brandName values differ by locale.

If your brandName values vary from locale to locale, you must pass a consistent brandId value and localized brandName value for each Brand across all locales. If you do not include brandId values in these scenarios, Bazaarvoice will auto-generate the brand ID using the localizedbrandNames. This will cause confusion within the Bazaarvoice catalog system for which Brand to associate with the given product.

        <b>Code examples</b>
        <p>Example of providing only <code>brandName</code>:</p>
        <pre class="prettyprint" xml:space="preserve">...
    catalogProducts: [{
        ...           
        "brandName":"MyBrand",
        ...
    }]
  }; ...</pre>
        <p>Example of providing <code>brandId</code> and <code>brandName</code>:</p>
        <pre class="prettyprint" xml:space="preserve">...
     catalogProducts: [{
        ...
        "brandId":"789",           
        "brandName":"MyBrand",
        ...
    }]
  }; ...</pre>

Categories

A product can be associated with only one parent Category entity in your product catalog. A Category entity has a single unique category id with localized category Name values (if provided in your catalog data). There are two ways to provide Category data via DCC, depending on how many locales are specified in your implementation.

Single locale implementation

If your implementation only uses one locale, only category Name is required. Bazaarvoice will auto-generate category id values using the category name provided.

Note: You can provide your own category id values if you have defined them already and want Bazaarvoice to use them in your product catalog instead.

Multi-locale implementation

If your implementation uses multiple locales, how you provide Category data depends on whether category Name values differ by locale.

If your category Name values vary from locale to locale, you must pass a consistent category id value and localized Name value for each Category across all locales. If you do not include id values in these scenarios, Bazaarvoice will auto-generate the category ID using the localizedNames. This will cause confusion within the Bazaarvoice catalog system for which Category to associate with the given product.

Code examples

Example of providing category id and category Name values:

...
    "categoryPath" : [
          {
            "id" : "123",
            "Name" : "Parent Category Name"         // Parent
          },
          {
            "id" : "123-1",                       // Child1
            "Name" : "Mens"
          },
          {
            "id" : "123-1-9",                     // Child2
            "Name" : "Pants"
          }
        ]
    },
...

Example of providing only category Name values:

...
    "categoryPath" : [
          {
            "Name" : "Parent Category Name"         // Parent
          },
          {
            "Name" : "Mens"                       // Child1
          },
          {
            "Name" : "Pants"                      // Child2
          }
        ]
    },
...

Step 3: Request to run the DCC Accelerator

To prevent Bazaarvoice from waiting for each product display page to be visited once in order to collect catalog data for all of your products, Bazaarvoice has created the DCC Accelerator. DCC Accelerator is a one-time tool used during implementation to "walk" (traverse various pages on) your website, visiting each product display page in the process. Each page "view" will trigger DCC for that page. After the "walk" process is complete, Bazaarvoice should have product catalog data for all products (with product display pages) on your website.

Note: When you have finished adding DCC JavaScript to your product display pages, contact Bazaarvoice Client Care to run the DCC Accelerator.

Combine DCC with product catalog feeds

DCC can be combined with product catalog feeds. This hybrid approach is useful in situations where all required catalog data is not available in the DCC JavaScript. Typically, your JavaScript data would be missing GTINs (UPC, EAN, and ISBN). You can provide this missing data by using simple CSV files. Refer to Use multiple catalog sources for more information on using multiple sources to provide catalog data to Bazaarvoice.

Active and inactive status

DCC can rely on one or both of the following mechanisms for controlling when a product, brand, or category is active or inactive:

We recommend using the Bazaarvoice-controlled inactivity capability. Use the inactive data element if you want the active/inactive state of a product to be tied to the state of something other than the existence of the product's PDP. For example, this could be useful when you want a product's active/inactive state to be tied to the in-stock/out-of-stock state.