You can also provide your catalog data using a text feed. The primary benefit of this product feed type is that it is relatively easy for clients with smaller catalogs to manually create. However, there are also several limitations which are described in the following section.

Create a text product catalog feed

Bazaarvoice supports receiving catalog data in a text file. Though this format can be used to provide the main catalog feed, Bazaarvoice recommends that you use the text format for supplemental feed files because the text format has the following limitations:

  • Lack of localization—You cannot provide localized catalog attributes such as product name, category name, and URLs.
  • Simple category hierarchy—Though the text format supports category information, only non-localized category names can be provided in a text file. Unique category identifiers cannot be sent to Bazaarvoice in a text file; if they are, downstream issues may occur if category names change over time for any reason.

    • Strict limitations on field values—You must adhere to the following rules when creating a text feed:

  • Do not include instances of a delimiter (commas, pipes, or tabs) within the field values, such as Name or Description.
  • Do not use double-quotes around field values.
  • Avoid including leading and trailing spaces in field values because they will be included with the value when stored in the Bazaarvoice database.

Complete the steps in this section to provide catalog data to Bazaarvoice in the form of a text file.

Step 1: Create and format the text file

The following sections detail the exact specifications of the Bazaarvoice text feed file.

File attributes

The file must be formatted as follows:

File Attribute Description
Header

Must be listed as the first line in the file and begin with //. Include a header for specific scenarios when using multiple catalog sources, such as when using a text file as your main feed in conjunction with multiple catalog feed sources. Here is an example:

//catalogMode=COMPLETE
Delimiter

Use one of the following delimiters to separate columns:

  • Comma
  • Pipe (I)
  • Tab

Column Header Row

Required to describe the values provided in the file. The file must include at least two columns. Refer to Column definitions for a list of headers and values that can be included in the file.

File extension

You can use any file extension when naming the feed file because Bazaarvoice automatically detects the file type. However, Bazaarvoice recommends using common extensions, such as .csv, .tsv, or .txt.

Columns definitions

The following columns are supported in the text file. Note that column names are not case sensitive.

Column Name Value Required
ExternalId

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.

 Yes
Name

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

 No
Description

Description of the product. A description is only used within the optional Facebook Ratings & Reviews or Questions & Answers app. Bazaarvoice recommends that product descriptions be at least three sentences or 300 characters long.

 No
Brand

The name of the brand to which the product belongs.

Note: If BrandExternalId is not specified in addition to Brand, a brand external ID is created even if a brand external ID was specified in a feed or created in the past.
 Recommended
BrandExternalId

ID of the brand to which the product belongs.

 Recommended
Category

The product's category name.

 Recommended
CategoryExternalId

Category ID for the product.

Note: If CategoryExternalId is not specified in addition to Category, a category external ID is created even if a category external ID was specified in a feed or created in the past.
 Recommended
ProductUrl

Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. 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 ([ ]).

 Yes
ImageUrl

Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. 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.
 Yes
ModelNumber 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. No; if included, one per product
ManufacturerPartNumber Manufacturer-specific part number (MPN). Part numbers can contain letters, numerals, and characters. Recommended
EAN

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.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
UPC

Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. A UPC 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 EANs. Values are validated during the catalog import process, however, and only valid values are stored.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
ISBN 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.

Either EANs, UPCs, or ISBNs is required.

If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
GTIN Global Trade Item Number (GTIN), which is a globally unique 14-digit number used to identify trade items, products, or services. Bazaarvoice auto-detects the type of value provided in the GTIN field and stores it as the appropriate UPC, EAN, or ISBN value in the Bazaarvoice database. No
BV_FE_Family The product family name to which the product belongs. Bazaarvoice recommends that you exclude special characters from product family names. No
BV_FE_Expand The product bundle name, to enable a product to display all content about family components on the product bundle's page. No
Inactive

Marks the product inactive if a yes or true value is specified in this column.

Note: If the product does not exist in the database and is marked inactive, it is not added to the database.
 No

Product attributes with multiple values

If a product has more than one value for an attribute, you should provide all values if possible to maximize the value of the Bazaarvoice network. For example, a shirt may have different SKUs in your catalog system, one for each color or size variant. Bazaarvoice supports multiple values for the following product attributes:

  • UPC
  • EAN
  • ISBN
  • GTIN
  • ManufacturerPartNumber
  • ModelNumber

To provide multiple values for an attribute, you can

  • Combine values into a single column and separate the values using spaces. Here is an example:
    ExternalId | UPC  
    123 | 123000000001         
    456 | 456000000001 456000000002 456000000003
    788 | 789000000001 789000000002
  • Repeat the product in the file, providing a different value on each line. Here is an example:
    ExternalId, UPC
    123,123000000001
    456,456000000001
    456,456000000002
    789,789000000001
    789,789000000002
    789,789000000003

Step 2: Upload the feed

Bazaarvoice recommends that you upload an updated product feed whenever changes are made to your product catalog as reflected by your website. It is imperative that you provide Bazaarvoice with matching updates as your product catalog changes on your live site.

Note: If you are attempting to provide product catalog data using multiple sources, contact Bazaarvoice to enable this functionality before uploading the feed file.

You can add another level of security to your data by supplying a public Secure Socket Shell (SSH) key using SSH passwordless entry. This process relies on a private key that resides with you, paired with a public key used by a Bazaarvoice SFTP server. If you want to set up this key-based authentication method, contact Bazaarvoice Support for information and assistance.

Upload the feed file to the /import-inbox directory of the SFTP server:

  • If your data is hosted in the US, use the following URLs:
    • Staging server—sftp-stg.bazaarvoice.com
    • Production server—sftp.bazaarvoice.com
  • If your data is hosted in Europe, use the following URLs:
    • Staging server—sftp7-stg.bazaarvoice.com
    • Production server—sftp7.bazaarvoice.com

Be sure to connect to SFTP using port 22. Contact Bazaarvoice Support if you do not know your SFTP credentials or where your data is hosted.

After you upload a product feed to an SFTP server, Bazaarvoice automatically begins importing the feed at 2 AM Central Time (CST: UTC-6 or CDT: UTC-5), although Bazaarvoice may not finish importing your feed until later the same day due to the import process.

If you uploaded the feed to a staging server, you can trigger an import manually. (You cannot manually trigger an import to the production server.) Complete the following steps to manually import the feed:

  1. From the Workbench of your staging server, select Settings > Validate Product Feed.
  2. Select Schedule one-time import to manually import the feed.

Step 3: Check the feed status

After uploading a feed to the staging or production SFTP server, you can view the import summary and error or warning count of the feed. Checking the import summary enables you to correct errors before the next import, so you can ensure you provide a valid feed for the next import.

View the import summary in the Workbench for your staging or production server by selecting Settings > Validate Product Feed. If your feed returns an error or warning, select it for more information.

Example text feeds

The following example is a simple comma-separated value (CSV) file that provides supplemental EAN catalog data:

ExternalId, EAN
123,0123000000001
456,0456000000001
456,0456000000002
789,0789000000001
789,0789000000002
789,0789000000003

Here is an example of a CSV file that can be used as the primary feed for product catalog data:

//catalogMode=COMPLETE
ExternalId, UPC    
123,123000000001
456,456000000001
456,456000000002
789,789000000001
789,789000000002
789,789000000003

Incremental feed files

A full product catalog feed includes all products that are available in your catalog and for which you want to collect content. An incremental feed contains data for a subset of your products.

Consider the following strategies for using full vs. incremental feeds:

  • Only full feeds

    You can upload a full, periodic, XML catalog feed to Bazaarvoice that includes all current data for all active products and categories. This is the recommended strategy.

  • Full and incremental feeds

    You can provide a mix of full and incremental catalog feeds. We recommend that you provide an initial full catalog feed followed by periodic, incremental feeds that contain only changes to your catalog data. Consider using full and incremental product feeds if:

    • Your product catalog changes so frequently that daily product feed updates are necessary
    • Infrequent or modest updates are made to your product feed

    However, to prevent gaps in the data set that can result from failure to upload and process any given incremental feed, we recommend that you provide a full feed periodically (with current data for your complete catalog) to ensure no data gaps exist.

  • Only incremental feeds

    If you cannot provide all products in a single, full catalog feed, you can provide incremental feeds only. Be sure to include the removed=”true” attribute when providing only incremental feeds. Refer to Control the active set of products for more information about this approach.

    Caution: If you use incremental feeds only and you never provide a full feed to Bazaarvoice, it is possible that catalog data may become out of sync with your source product catalog if an incremental feed upload is missed or fails in any way.

Each feed file indicates whether it is full or incremental, though this is done differently depending on the feed format:

  • XML feed files: use the incremental attribute in the <Feed> element
  • Text feed files: specify a file header

Share reviews using product families

The product families feature in Ratings & Reviews 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 for each 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 product feed or through the Workbench. You can assign a product to one or more families at the same time using 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: Product families only work for native reviews. Syndication ignores product family relationships. If you plan to or have implemented syndication, contact Bazaarvoice Support before configuring product families in your product feed.

Using the product feed

We recommend 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: We recommend 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.