If maintenance-free PIE is not implemented, Bazaarvoice will also accept an XML feed with transactions in order to send out PIEs.

PIE campaigns can be implemented by using either of the following integration methods:

  • White-label – Full-service option in which Bazaarvoice delivers PIE messages in conjunction with an industry-leading email service provider (ESP). Clients are not required to engage with or establish an account or contract with this provider.
  • Partner-integrated – With this option, Bazaarvoice triggers PIE messages through existing integrations with a short list of industry-leading ESPs. Your ESP might require additional fees to implement a partner-integrated PIE campaign. Contact Bazaarvoice for a list of supported ESP partners.

Bazaarvoice requires a regularly scheduled interaction-data feed to power either of these integration methods. For more information, see File types.

Creating PIE feeds

Data from your online interactions must be sent to Bazaarvoice according to the requirements that this section identifies.

If you collect email addresses during a purchase transaction in your brick-and-mortar store, you can send us this purchase data for PIE delivery as long as the feed meets the requirements listed in this section.

Tapping into this data source has two advantages:

  • Significantly increase review volume – some clients have seen a 2x increase in review submissions
  • Introduce offline customers to your online experience

The PIE interaction-data feed for non-transactional PIEs can, at a minimum, contain a list of email addresses of the intended PIE recipients.

File types

Data sent to Bazaarvoice for PIEs, is referred to as the interaction-data feed. This feed must be in one of the following file formats:

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

Each 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, such as the following example:

  • YourSiteName_InteractionData_20120928.txt
  • YourSiteName_OrderData_20120928.xml

If you intend to send multiple feeds a day, add a unique character to the file name. For example:

  • YourSiteName_InteractionData1_20120928.xml
  • YourSiteName_InteractionData2_20120928.xml

Tab-delimited interaction feeds

Tab-delimited PIE text files support two kinds of columns: “interaction” columns and “product” columns. Interaction columns appear before product columns, and each column only appears once. 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

Utilize the following best practices when you create a tab-delimited PIE 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 utilize header rows to denote column names; Bazaarvoice will ignore these rows.

Interaction data feed file

As an XML document, the interaction data feed file begins with a root node of <Feed xmlns="http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/5.6" >, and 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 exhibits all possible elements:

<?xml version="1.0" encoding="UTF-8"?>
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/5.6">
    <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>

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

Validating XML interaction feeds

You can validate your XML interaction feeds using a local validator such as XMLBeans before submitting them to Bazaarvoice. To do so, follow these steps:

  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 against on your local machine. To do this, visit the site defined in the xmlns (For example: http://www.bazaarvoice.com/xs/PRR/PostPurchaseFeed/5.6) and save the output as an XSD file on your machine.
  3. From there, you will be able to use the command line to call XMLBeans to validate your file. 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

Data fields for transactional PIEs

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

FieldBest practice for PIE?Required?Description
TransactionDateYesYes, if using send delayThe purchase, shipping, or other interaction date. Bazaarvoice supports the following date formats:
  • yyyy-MM-ddTHH:mm:ss (2012-09-21T11:36:47)
  • yyyy-MM-ddTHH:mm:ss.SSS (2012-09-21T11:36:47.384)
  • yyyy-MM-ddTHH:mm:ssZ (2012-09-21T11:36:47.0500)
Locale (includes language and country information)YesYes, if supporting PIE in multiple languagesControls the language-specific email template that is used, as shown by the following examples:
  • en_US for English
  • es_US for Spanish
EmailAddressYesYesEmail address of customer. Must be in a valid format.
UserIdYesNoCustomer'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.

UserNameYesYes if you want to:
  • auto-populate the nickname field on the submission form
  • address the email recipient by their user name in the PIE (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 PIE is five.

FieldBest Practice for PIE?Required?Description
ExternalId (product)YesYesMust match the external product ID for the item that is sent to Bazaarvoice in your product-catalog data feed.
ImageUrl (product)YesYes

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

PriceYesNo, but recommendedUsed 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, e.g., "20.99", "40.00"

Data fields for non-transaction PIEs

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

FieldBest practice for PIE?Required?Description
TransactionDateYesYes, if using send delayThe purchase, shipping, or other interaction date. Bazaarvoice supports the following date formats:
  • yyyy-MM-ddTHH:mm:ss (2012-09-21T11:36:47)
  • yyyy-MM-ddTHH:mm:ss.SSS (2012-09-21T11:36:47.384)
  • yyyy-MM-ddTHH:mm:ssZ (2012-09-21T11:36:47.0500)
Locale (includes language and country information)YesYes, if supporting PIE in multiple languagesControls the language-specific email template that is used, as shown by the following examples:
  • en_US for English
  • es_US for Spanish
EmailAddressYesYesEmail address of customer. Must be in a valid format.
UserIdYesNoCustomer'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.

UserNameYesNot 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 PIE (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 PIE. The maximum number of events that will be listed on a PIE is five.

FieldBest practice for PIE?Required?Description
ExternalId (product)YesNo, but recommendedMust match the external product ID for the item that is sent to Bazaarvoice in your product-catalog data feed.
ImageUrl (product)YesNo, but recommendedProduct 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)YesNo, but recommendedWill 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;)

PriceYesNo, but recommendedUsed 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, e.g., "20.99", "40.00"

Uploading PIE feeds

Note:  This section only applied to client who are implementing manual feed-based PIE. If you are implementing maintenance-free PIE, you can ignore this section.

You will need the following values to upload your interaction data feed file to the Bazaarvoice SFTP location. The following is an example, contact Bazaarvoice support if you do not know the values of the various credentials listed here:

  • Staging server – sftp-stg.bazaarvoice.com
  • Production server – sftp.bazaarvoice.com
  • Secure user name – example
  • Secure password – password123123123
  • Directory – ppe/inbox

The following image shows the location of this directory.

Frequency of interaction-data feed

You can specify the frequency with which the interaction-data feed is sent to Bazaarvoice as long as you do not send more than one feed every 24 hours. Bazaarvoice recommends that you schedule the feed to run daily.

Scheduling the interaction-data feed and PIE

You can determine how soon after an interaction to send a PIE to a customer for feedback on your products or services. After you determine a schedule for your PIEs, you can send Bazaarvoice the interaction-data feed anytime from the interaction event until 24 hours before the delivery date of the PIE.

Bazaarvoice recommends the following schedule:

  • Delay sending the data feed to Bazaarvoice by 20 days from the date of the interaction.

    Bazaarvoice send a PIE for every record in your interaction-data feed. If you are concerned about sending a PIE to customers who have either cancelled or returned products, you can remove cancelled and returned items from the interaction-data feed before delivering it to Bazaarvoice.

  • Deliver PIE 21 days after interaction date.

The following table lists the scheduling options for PIE.

OptionPossible valuesRecommended value* (default)
Frequency of interaction-data feed sent to BazaarvoiceDaily or weeklyDaily
Number of days between interaction event and PIE deliveryOne to several days21 days
Maximum number of products or services listed on a PIE1 to nFive products or services

* If you do not specify values for the above options, the defaults listed will be used (see the Recommended value column).

Example scenarios

The following image illustrates a scenario in which a client sends Bazaarvoice the interaction-data feed 24 hours before a PIE is scheduled for delivery to customers.

The following image illustrates a scenario in which a client sends Bazaarvoice the interaction-data feed shortly after the interaction date.