Dynamic Catalog Collection-Signed events

Dynamic Catalog Collection (DCC) allows Bazaarvoice to collect and consume product catalog data. 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. DCC supports the collection of both new product catalog data and updates to previously provided catalog data.

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 that 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.

Before you begin

Contact Bazaarvoice Support 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

Enter a passphrase when prompted. This passphrase adds an additional security layer to the keys you generate. For detailed information on passphrases, refer to GitHub documentation.

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.

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 (in the main_site deployment zone).
Contact Bazaarvoice support to add these generated keys.

Step 2: Implementing server-side data

The recommended approach will be to:

Modify the product data javascript so it is in the correct format for DCC.
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 .

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));

Expose the signed data to the front-end javascript using an API.
Expose your code to the front-end as window.dccSignedTokens.

Step 3: Implementing front-end data

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

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.length; i

Single-product PDP:

<script async type="text/javascript">
window.bvCallback = function (BV) {
BV.pixel.trackEvent("CatalogUpdate", {
type: 'Product',
token: window.dccSignedToken
});
};
</script>

If you are upgrading from DCC legacy to DCC signed events, simply replace the existing “CatalogUpdate” DCC javascript on the PDP with one of the above implementations.

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. For more information on key product elements, see Required product data.

Attribute	Value	Required
`productId`	Unique product ID that can contain only alphanumeric characters, hyphens (`-`), and underscores (`_`).The product ID is defined within the `div` tag where the data-bv-show attribute appears on your product page. If your current implementation uses the scout file (`bvapi.js`), you can set the product ID in the `$BV.ui` configure call on your product page. 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 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. 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. 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.