Note: If BV Pixel to power review request is not implemented, for whatever business reason, Bazaarvoice will accept an XML feed containing your transaction data to send out review requests.

Even if you are using BV Pixel to power review requests, the feed-based method can be useful for sending review requests to email addresses collected during a purchase transaction in your brick-and-mortar store.

Send interaction data manually

Follow these steps to send interaction data manually:

Step 1: Create interaction feeds
Step 2: Validate XML interaction feeds
Step 3: Upload interaction feeds
Step 4: Schedule the interaction data feed and review requests

HTML example code

For additional guidance, refer to these full HTML examples.

Step 1: Create interaction feeds

In addition to transaction data collected online, you can collect email addresses during a purchase transaction in your brick-and-mortar store.

You can also collect review request interaction-data feed for non-transaction review requests. At a minimum, a non-transactional interaction feed must contain a list of email addresses of the intended review request recipients.

Note: Non-transaction data is data generated by clicks on newsletter signups, product registration, Where-to-Buy links, or PDF downloads.

Data sent to Bazaarvoice from online interactions (to be fed into review requests) must be sent in one of these formats:

  • An XML file (preferred)
  • A tab-delimited text file

Refer to Review request file types for more detailed information on both of these formats.

If you intend to send multiple feeds a day, add a unique character to each file name (to differentiate them). For example:

  • YourSiteName\_InteractionData1\_20190928.xml
  • YourSiteName\_InteractionData2\_20190928.xml

Each tab-delimited file uploaded must have a unique name to avoid it overwriting the previous file. We accept any naming convention you choose but recommend including your site name and current date. For example:

  • YourSiteName\_InteractionData\_20190928.txt
  • YourSiteName\_OrderData\_20190928.xml

Option 1: XML interaction data feed file

An XML based data interaction file should begin with a root node and follow this XML schema .

Each transaction in the feed features its own Interaction element under the root. Transaction-related metadata appears as children elements like TransactionDate under the appropriate transaction.

The following example shows the general structure of a simplified XML interaction feed that shows all possible elements:

<?xml version="1.0" encoding="UTF-8"?>
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/14.7">
    <Interaction>
        <TransactionDate>...</TransactionDate>
        <EmailAddress>...</EmailAddress>
        <UserName>...</UserName>
        <UserID>...</UserID>
        <Locale>...</Locale>
        <Products>
            <Product>
                <ExternalId>...</ExternalId>
                <Name>...</Name>
                <ImageUrl>...</ImageUrl>
                <Price>...</Price>
            </Product>
        </Products>
    </Interaction>
</Feed>

Use the following best practices when you create an interaction data feed file (XML interaction feed).

  • Interaction dates must conform to the XML dateTime format. For example:

    2010-10-10T11:11:11.000
    
  • Ensure that the first line of your feed adheres to the following format:

    <?xml version="1.0" encoding="utf-8"?>
    
  • The standard character-encoding scheme, such as UTF-8 or Windows-1252, must match the scheme that you use for any special characters in the feed.
  • If you do not have a value for a particular field, omit the field from your feed. Do not include the field with a blank value.

Option 2: Tab-delimited interaction feed file

Tab-delimited review request text files support two kinds of columns:

  • Interaction: Interaction columns appear before product columns, and each column only appears once.
  • Product: Product columns appear after interaction columns, and can occur in repeating sets (maximum of 5) to define multiple products as part of a single interaction.

The following columns are interaction columns:

  • Interaction date
  • Locale
  • Email address
  • User ID
  • User name

The following columns are product columns:

  • Product ID
  • Product name
  • Product thumbnail image URL
  • Product price

The following example shows the general structure of a simplified tab-delimited interaction feed with interaction date, email address, and user ID “interaction” columns, and varying numbers of repeating sets of product ID, product thumbnail image URL, and product name “product” columns:

date  email  userId  productId  imageUrl  productName
date  email  userId  productId  imageUrl  productName  productId  imageUrl  productName
date  email  userId  productId  imageUrl  productName
date  email  userId  productId  imageUrl  productName  productId  imageUrl  productName

Use the following best practices when you create a tab-delimited review request interaction feed.

  • Interaction dates can be in any format that can be expressed via the methods defined in Java’s SimpleDateFormat class. Bazaarvoice recommends the following format:

    yyyy-MM-dd HH:mm:ss.SSS
    
  • Feeds may use header rows to denote column names; Bazaarvoice will ignore these rows.

Data fields for transactional review requests

The following table identifies the required or recommended fields for transactional review requests:

Field Best practice for review requests? Required? Description
TransactionDate Yes Yes, if using send delay The purchase, shipping, or other interaction date. Bazaarvoice supports the following date formats:
  • yyyy-MM-ddTHH:mm:ss (2019-09-21T11:36:47)
  • yyyy-MM-ddTHH:mm:ss.SSS (2019-09-21T11:36:47.384)
  • yyyy-MM-ddTHH:mm:ssZ (2019-09-21T11:36:47.0500)
Locale (includes language and country information) Yes Yes, if supporting review requests in multiple languages Controls the language-specific email template that is used, as shown by the following examples:
  • en_US for English
  • es_US for Spanish
EmailAddress Yes Yes Email address of customer. Must be in a valid format.
UserId Yes No Customer's user ID, typically created during an online transaction. This value is encoded into the Bazaarvoice user authentication string (UAS).

The user ID in the interaction-data feed must match the user ID that is passed to Bazaarvoice during the review-submission process (as part of your ratings and reviews implementation). This field can be blank on purchase records for which a user ID was not generated during the checkout process, such as a guest purchaser.

If the same user ID occurs in the same feed more than once with different email addresses, the user ID will be set to null and a warning is printed to the log file.

This field should be omitted if using Bazaarvoice hosted authentication.

UserName Yes Yes if you want to:
  • auto-populate the nickname field on the submission form
  • address the email recipient by their user name in the review requests, for example, “Hi Vicki”
User's first name or nickname created by the customer on an online account. This field can be used to personalize the email greeting.

The following fields apply to each product or service in the interaction. The maximum number of products that will be listed on a review request is five.

Field Best Practice for review requests? Required? Description
ExternalId (product) Yes Yes Must match the external product ID for the item that is sent to Bazaarvoice in your product-catalog data feed.
ImageUrl (product) Yes Yes

If you cannot provide a URL to the image, a customizable "no image available" graphic is displayed.

Product thumbnail will be displayed in the email template. Always provide the full URL including "http://www". If not provided, it will be retrieved from your current product database.
Name (product) Yes Yes Will be used in the email template. If not provided, it will be retrieved from your current product database. In XML feeds, it puts names in CDATA sections: <![CDATA[Your_Product_Name]]>

Replace special characters with the HTML entity number equivalent (® = &#174;)

Price Yes No, but recommended Used to control the order in which products appear within a given email (such as list highest value product first). Should be a decimal number with no currency symbols, for example, "20.99", "40.00"

Data fields for non-transaction review requests

The following table identifies the required or recommended fields for non-transaction review requests:

Field Best practice for review requests? Required? Description
TransactionDate Yes Yes, if using send delay The purchase, shipping, or other interaction date. Bazaarvoice supports the following date formats:
  • yyyy-MM-ddTHH:mm:ss (2019-09-21T11:36:47)
  • yyyy-MM-ddTHH:mm:ss.SSS (2019-09-21T11:36:47.384)
  • yyyy-MM-ddTHH:mm:ssZ (2019-09-21T11:36:47.0500)
Locale (includes language and country information) Yes Yes, if supporting review requests in multiple languages Controls the language-specific email template that is used, as shown by the following examples:
  • en_US for English
  • es_US for Spanish
EmailAddress Yes Yes Email address of customer. Must be in a valid format.
UserId Yes No Customer's user ID, typically created during an online transaction. This value is encoded into the Bazaarvoice user authentication string (UAS).

The user ID in the interaction-data feed must match the user ID that is passed to Bazaarvoice during the review-submission process (as part of your ratings and reviews implementation). This field can be blank on purchase records for which a user ID was not generated during the checkout process, such as a guest purchaser.

If the same user ID occurs in the same feed more than once with different email addresses, the user ID will be set to null and a warning is printed to the log file.

This field should be omitted if using Bazaarvoice hosted authentication.

UserName Yes Not required unless you want to:
  • auto-populate the nick name field on the submission form
  • address the email-recipient by their user name in the review request (example, “Hi Vicki”)
User's first name or nickname created by the customer on an online account. This field can be used to personalize the email greeting.

The following fields apply to each non-transaction event you want to list on a review request. The maximum number of events that will be listed on a review request is five.

Field Best practice for review requests? Required? Description
ExternalId (product) Yes No, but recommended Must match the external product ID for the item that is sent to Bazaarvoice in your product-catalog data feed.
ImageUrl (product) Yes No, but recommended Product thumbnail will be displayed in the email template. Always provide the full URL including "http://www". If not provided, it will be retrieved from your current product database.
Name (product) Yes No, but recommended Will be used in the email template. If not provided, it will be retrieved from your current product database. In XML feeds, it puts names in CDATA sections: <![CDATA[Your_Product_Name]]>

Replace special characters with the HTML entity number equivalent (® = &#174;)

Price Yes No, but recommended Used to control the order in which products appear within a given email (i.e. list highest value product first). Should be a decimal number with no currency symbols, for example, "20.99", "40.00"

Step 2: Validate XML interaction feeds

Validate your XML interaction feeds using a local validator such as XMLBeans before submitting them to Bazaarvoice.

  1. Visit http://xmlbeans.apache.org/ and install XMLBeans. Installation steps will vary by operating system and platform.
  2. Save a copy of the Bazaarvoice schema you are attempting to validate to your local machine. To do this, visit the site defined in the xmlns and save the output as an XSD file on your local machine.
  3. On your local machine, use the command line to call XMLBeans to validate your file.
Note: Full documentation of the XMLBeans command line tools can be found here: http://xmlbeans.apache.org/docs/2.0.0/guide/conValidationWithXmlBeans.html#command\_line\_validation

Step 3: Upload interaction feeds

Note:  Use this section if you're sending interaction data manually.

You will need the following values to upload your interaction data feed file to the Bazaarvoice SFTP location. The following is an example:

  • Staging server: sftp-stg.bazaarvoice.com
  • Production server: sftp.bazaarvoice.com
  • Secure user name: example
  • Secure password: password123123123
  • Directory: ppe/inbox
Note: Contact Bazaarvoice Support if you don't know the values of the credentials listed.

Step 4: Schedule the interaction-data feed and review requests

You can specify how often your interaction-data feed should be sent to Bazaarvoice. We recommend that you schedule the feed to run once daily.

Decide how soon after an interaction you want to send a review request to a customer for feedback. You can send Bazaarvoice the interaction-data feed anytime from the interaction event until 24 hours before the delivery date of the review requests.

Best practices when scheduling

Bazaarvoice recommends the following schedule:

  • Deliver review requests 21 days after interaction date.
  • Delay sending the data feed to Bazaarvoice by 20 days from the date of the interaction.
  • Remove cancelled and returned items from the interaction-data feed before delivering it to Bazaarvoice. Bazaarvoice sends a review request for every record in your interaction-data feed. So if you’re concerned about sending a review request to customers who have either cancelled or returned products, remove these items from the feed.

The following table lists the default scheduling options for review requests.

Note: If you do not specify your own values for these options, the default values listed will be used.
Option Possible values Recommended value (default)
Frequency of interaction-data feed sent to Bazaarvoice Daily or weekly Daily
Number of days between interaction event and review request delivery One to several days 21 days
Maximum number of products or services listed on a review request 1 to n Five products or services

Review requests campaigns

Review requests campaigns can be implemented by using either of the following feed-based integration methods:

  • Option 1: White-label. Full-service option where Bazaarvoice delivers review requests in conjunction with an industry-leading email service provider (ESP).
    Note: Clients are not required to engage with the email service provider (ESP).
  • Option 2: Partner-integrated. Bazaarvoice triggers review requests through your existing email integration. Your ESP might require additional fees to implement a partner-integrated review request campaign.

    Note: Contact Bazaarvoice Support for a list of supported ESP partners.

Example feeds

To assist with your implementation, refer to Ratings & Reviews knowledge base for the following example feeds and formats: