Note: If maintenance-free PIE (BV Pixel) is not implemented, for whatever business reason, Bazaarvoice will accept an XML feed containing your transaction data to send out PIE messages.

Even if you are using maintenance-free PIE (BV Pixel), the feed-based method can be useful for sending PIE messages to email addresses collected during a purchase transaction in your brick-and-mortar store.

Implementing feed-based PIE

Follow these steps to implement feed-based PIE:

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

HTML example code

For additional guidance, refer to these full HTML examples.

Step 1: Create PIE 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 PIE interaction-data feed for non-transaction PIE messages. At a minimum, a non-transactional PIE feed must contain a list of email addresses of the intended PIE 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 PIE messages) must be sent in one of these formats:

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

Refer to PIE 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 PIE 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 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 use header rows to denote column names; Bazaarvoice will ignore these rows.

Data fields for transactional PIEs

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

Field Best practice for PIE? 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 PIE 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 PIE, 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 PIE is five.

Field Best Practice for PIE? 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 PIEs

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

Field Best practice for PIE? 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 PIE 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 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.

Field Best practice for PIE? 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 PIE feeds

Note:  Use this section if you're implementing manual feed-based PIE.

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 Client Care if you don't know the values of the credentials listed.

Step 4: Schedule the interaction-data feed and PIE

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

Best practices when scheduling

Bazaarvoice recommends the following schedule:

  • Deliver PIE 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 PIE for every record in your interaction-data feed. So if you’re concerned about sending a PIE to customers who have either cancelled or returned products, remove these items from the feed.

The following table lists the default scheduling options for PIE.

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 PIE delivery One to several days 21 days
Maximum number of products or services listed on a PIE 1 to n Five products or services

PIE campaigns

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

  • Option 1: White-label. Full-service option where Bazaarvoice delivers PIE messages 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 PIE messages through your existing email integration. Your ESP might require additional fees to implement a partner-integrated PIE campaign.

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

Example feeds

To assist with your implementation, refer to Bazaarvoice’s Conversations knowledge base for the following example feeds and formats: