Using the API to Build Emplifi Ratings & Reviews

In this article, we walk through how to reconstruct Emplifi Ratings & Reviews widgets using the TurnTo API. In a widget implementation, Ratings & Reviews includes a product review summary, a review list, and a create-a-review workflow. Let's go through them one by one.

For additional detail about how these elements function in a widget-based installation, see the Review Display Widgets article.

Building the Product Review Summary

Before displaying product reviews, which we'll get to in the next section, Emplifi recommends showing a summary with aggregate rating and review information.

In an API implementation, the product review summary is also known as the UGC summary and is a collection of data points relating to a particular catalog item, such as the number of questions, number of reviews, and average rating.

To display the product review summary:

1. Familiarize yourself with the UGC Summary API endpoint reference documentation.

2. Determine which fields you want to show in your product review summary. The content of the product review summary section depends on the review attributes that you collect.

3. Set up your product detail page (PDP) with a product review summary section.

Building the Review List

Now it's time to display your product reviews.

To display the review list:

1. Familiarize yourself with the Review List API endpoint reference documentation.

2. Determine which fields you want to show in your review list.

3. Set up your PDP with a review list section.

Building the Create a Review Form

Set up your site to drive users to your Review Collection form. Most sites will include a Write a Review button within the PDP.

To set up the review collection process:

1. Decide which fields to collect

2. Develop your Review Collection form

3. Determine how to use the API response from the submitted review

4. (Optional) Create a 'Do More' feature

1. Decide which fields to collect

Determine the fields you want to collect for each review, being sure to specify the field type and whether the field is optional or required.

Emplifi requires these fields:

• A user identifier.

  • For an existing user, provide either user.emailAddress or a unique user.externalId.

  • For a new user, provide user.firstname and user.lastname.

• rating - product rating on a 1-5 scale

• catalogItems[].sku - the product SKU that is being reviewed

Other than that, you should choose fields that are important to your business. When you have selected the fields you want to collect, send that information to the Emplifi Customer Success team.

2. Develop your Review Collection form

Next, create the form that will collect the rating and review data. Here is an example form, broken down by sections:

• Header
  We open our form with text asking the user to complete the form. We include details for the product being reviewed, such as name and images. We also add a link to open a drawer displaying our review guidelines (such as no profanity, no advertising, etc.).

• Body
  The body of the review requests an overall rating on a 1-5 scale, a review body for the main text of the review, and also a review title. In this case, we make the review title optional. We also allow the user to submit any photos or videos they may have.

• Submit Button
  We end the form with a Submit button. The Submit button should send a POST request to the /v1.3/reviews endpoint. For details, see Create Review in the API documentation.

3. Determine how to use the API response from the submitted review

Consider whether you want to build any interactions based on the data returned in the API response from the submitted review.

After a review submission the API responds with:

• the information provided in the review that was just submitted

• the overall product review summary

• user information summary collected for the email address or external ID, if any

• a summary of the media collected, if the user attached any media

For more detail, expand the Response 201 area in the Create Review API endpoint reference documentation.

4. (Optional) Create a 'Do More' feature

Consider creating a 'Do More' feature to collect more content from a user already in the mode of writing reviews.

To access a user's unreviewed purchases, see the Unreviewed Purchases API endpoint reference documentation.