JavaScript Order Feed

During the integration process before the system is live, clients typically provide Emplifi with a one-time Historical Order Feed that populates Emplifi Ratings & Reviews with past order data. While live, the JavaScript Order feed passes newly placed orders from the order confirmation page to Emplifi Ratings & Reviews. To update existing order data, such as changing estimated delivery dates, use the historical order feed.

We recommend adding this JavaScript code to your production site prior to going live so you can start to build your product owner pools early on.

Installing the JavaScript Order feed

Steps:

Place the following code into the <head> of your order confirmation page, replacing <SITE KEY> with your Emplifi Ratings & Reviews Site Key:

JS

<script type="text/javascript">
  var turnToConfig = {
    locale: "en_US",
    pageId: "order-confirmation-page"
  }
  window.TurnToCmd=window.TurnToCmd||function(){(TurnToCmd.q=TurnToCmd.q||[]).push(arguments)};
</script>

<script src="https://widgets.turnto.com/v5/widgets/<SITE KEY>/js/turnto.js" async></script>

Create a JavaScript object that represents the order data to be passed via TurnToCmd. The code should be placed anywhere below the code placed in step (1).
Here's the object syntax with example data:

JS

<script type="text/javascript">
  TurnToCmd('feed.send', {
    orderId: 56754,
    email: 'email@address.com',
    postalCode: '12312',
    firstName: 'First',
    lastName: 'Last',
    nickName: 'nickName',
    total: 100.00,
    currency: 'USD',
    items: [
      {
        title: 'Epic React knit sweater',
        url: 'https://www.site.com/epic-react-knit-sweater-abc75M/AQ0001-001',
        itemImageUrl: 'https://i.site.com/epic-react-knit-sweater-abc75M/AQ0001-001.jpg',
        sku: 'AQ0001-001',
        qty: 2,
        price: 25.00
      },
      {
        title: 'Lunar Boot \'18',
        url: 'https://www.site.com/lunar-boot-defG1d/BR0001-001',
        itemImageUrl: 'https://www.site.com/lunar-boot-defG1d/BR0001-001.jpg',
        lineItemId: 'b',
        sku: 'BR0001-001',
        qty: 1,
        price: 50.00
      }
    ]
  });
</script>

Order data fields

Name	Required?	Description
orderId	Yes	The ID of the order.
email	Yes	The customer's email address. You must include either `email` or `externalUserId` in the feed, but are not required to include both. If you aren't sending emails through Emplifi Ratings & Reviews and don't want to pass customer email addresses, you can instead pass `externalUserId` as a unique identifier for the user.
firstName	Yes	The customer's first name.
lastName	Yes	The customer's last name.
nickName	No	A nickname for the customer.
postalCode	No	Postal code.
deliveryDate	No	The date by which the purchased item will be delivered to the customer. Value should be a string in `yyyy-MM-dd` format. For example, `2019-02-23` for February 23, 2019. If your site uses the Trigger initial RSE based on Delivery Date reviews setting, you must send this data point to calculate when to send your review solicitation emails. Without DELIVERYDATE details, review emails will not be sent out.
emailOptOut	No	Boolean. Default value is `false`. Set to `true` if the shopper should receive no emails from Ratings & Reviews.
total	No	The total cost of the order, which can optionally include discounts, taxes, etc. The value cannot contain currency symbols; `45`, `45.00` , and `"45.00"` are acceptable, but `"$45.00"` is not.
currency	No	The currency used in the transaction, expressed in 3 character country code (e.g., USD, see ISO 4217)
items	Yes	An array containing data about each line item in the order (see 'Line Item Fields' below for a list of objects in the items array).

Line item fields

Name	Required?	Description
sku	Yes	The SKU of the product.
title	No	The product name. This value never overwrites the catalog feed data for the SKU. If the purchased SKU isn't present in your catalog feed, this field ensures that the order feed continues to work.
url	No	The product URL on your site. This value never overwrites the catalog feed data for the SKU. If the purchased SKU isn't present in your catalog feed, this field ensures that the order feed continues to work.
itemImageUrl	No	The image URL for the product. This value never overwrites the catalog feed data for the SKU. If the purchased SKU isn't present in your catalog feed, this field ensures that the order feed continues to work.
qty	No	The number of product units purchased.
price	No	The price of the product. The value passed will never overwrite catalog feed data for the SKU. It's only used if the purchased SKU was not included in your catalog feed. The value cannot contain currency symbols; `45`, `45.00` , and `"45.00"` are acceptable, but `"$45.00"` is not.
lineItemId	No	The line item ID of the order.
siteKey	Required for multi-store clients	The Emplifi Ratings & Reviews Site Key of the store where the item was added to the cart.

Formatting data

To avoid breaking the JavaScript, you must properly escape order data values. For example, since order data strings are contained inside single quotes, any data values containing a single quote should be properly escaped (e.g., lastName: 'O\'Neill'). Other encoding issues may apply to your environment.

Building order data incrementally

The creation of the JavaScript order data object can be broken up over different script tags, if required by your application.

Steps:

Create the object with the base order data fields and an empty array for the line items, to be populated in the next step.

JS

<script type="text/javascript">
  var orderData = {
    orderId: '$myVariable',
    email: '$myVariable',
    postalCode: '$myVariable',
    firstName: '$myVariable',
    lastName: '$myVariable',
    total: 100.00,
    currency: 'USD',
    items: [];
  }
</script>

Add the line items while displaying each item.

JS

<script type="text/javascript">
  orderData.items.push({
    title: '$myVariable',
    url: '$myVariable',
    sku: 'AQ0001-001',
    itemImageUrl: '/my/site/AQ0001-001.jpg',
    qty: 1,
    price: '850.00'
  });
</script>

When the order object is fully populated, make the call to send the feed.

JS

<script type="text/javascript">
  TurnToCmd('feed.send', orderData);
</script>

Testing the feed installation

Steps:

Create a mock order on your order confirmation page.
Visit the page with Chrome Web Developer Tools (or Firebug from Firefox) open to the 'Console' tab.
Note any turnto.js errors, specifically those that start with TurnTo: (error) order feed - .
Search for the ttreqid call (example: en_US?ttreqid=1234...) and click on the second one. The Request Method should be POST, not OPTIONS.
Scroll to the bottom of the 'Headers' pane in the 'Request Payload' section to confirm that the correct order data is being passed.

If there are errors in the JavaScript Order feed or you need further assistance with troubleshooting, please contact your Emplifi Customer Success Manager.