DCC (legacy)

Caution: The following instructions are deprecated and are provided for technical reference only. Bazaarvoice recommends using DCC Signed Events for all new implementations. This updated method eliminates callback requirements and significantly reduces the risk of failed product updates in your catalog. 

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

Caution: If you have already added the BV loader while implementing Bazaarvoice-hosted display or BV Pixel, do not add it again. Add the BV loader only once on each page.

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.

Character encoding and special characters

DCC values are written directly into your page as JavaScript strings, so encoding and escaping errors corrupt the data that reaches your catalog. Most catalog corruption reported for DCC originates here.

1. Use UTF-8: Serve the PDP as UTF-8 and declare it in the <head>: <meta charset="UTF-8">. The page encoding must match the encoding your source system exports. If they differ, accented characters are corrupted before Bazaarvoice receives them — Café arrives as Café
2. Escape values as JavaScript, not HTML: Values such as productName, productDescription, brandName, and categoryName are JavaScript strings. Escape them according to JavaScript rules:
   
   

   Character	Use
   Double quote (")	\"
   Backslash (\)	\\
   Line break	\n
   </script> in any value	<\/script>

3. Do not use HTML entities. A product name written as Ben & Jerry's is stored literally as Ben & Jerry's and displayed that way to consumers. 
4. The reliable approach is to serialize the catalog object server-side with a JSON encoder rather than concatenating strings in a template. This escapes every value correctly and removes an entire class of syntax errors.
5. URL-encode reserved characters in URLs: productPageURL and productImageURL must be percent-encoded if they contain reserved characters — %20 for a space, %26 for an ampersand, %5B and %5D for square brackets ([ ]). Note that URLs use forward slashes. Backslashes in a JavaScript string are interpreted as escape sequences and will silently destroy the URL.
   
   

   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.bCallback = function(BV){
BV.pixel.tracjEvent("CatalogUpdate",{
type:'Product',
locale: window.bvDCC.catalogData.locale,
catalogProducts: window.bvDCC.catalogData.catalogProducts
});
};​

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.catalogProdutcs]
});
}
</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 %26 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 %26 for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]). Note: If Ratings & Reviews 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.

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.

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.

Example of providing only brandName:

...
catalogProducts: [{
...           
"brandName":"MyBrand",
...
}]
};
...

Example of providing brandId and brandName:

...
catalogProducts: [{
...
"brandId":"789",           
"brandName":"MyBrand",
...
}]
};
...

Categories

You can associate each product with a single parent product category entity in your product catalog. The maximum allowed category depth is 20 levels. A single category cannot have a chain of parent-to-child relationships that exceeds a total hierarchy depth of 20. 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.

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.

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.

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 Support 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:

• inactive data element in PDP JavaScript.
• Bazaarvoice-controlled inactivity capability. Refer to Control the active set of products for more details.

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.