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:
Familiarize yourself with the UGC Summary API endpoint reference documentation.
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.
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:
Familiarize yourself with the Review List API endpoint reference documentation.
Determine which fields you want to show in your review list.
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:
Decide which fields to collect
Develop your Review Collection form
Determine how to use the API response from the submitted review
(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 uniqueuser.externalId
.For a new user, provide
user.firstname
anduser.lastname
.
rating
- product rating on a 1-5 scalecatalogItems[].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.