@frontend-sdk/bigcommerce-reviews
v0.25.1
Published
BigCommerce Reviews integration for Shogun Frontend.
Downloads
117
Keywords
Readme
BigCommerce Reviews
BigCommerce Reviews integration for Shogun Frontend.
Enable users to submit product reviews to your BigCommerce store.
Overview
When a Shogun Frontend store is created and successfully connected to a BigCommerce store a full import is automatically run as part of the creation process. This process imports all Brands, Categories, and Products from BigCommerce and makes them available in the Shogun frontend CMS.
Reviews are considered part of a products data and as such are imported along with products during the initial import. As a result of this reviews are available for use in the CMS as a sub-field on a product.
You can get a feel for what fields will be available for use in your sections
and components by navigating to the Content
section of the app and selecting
a product. Scroll down to see the reviews:
Syncing
Shogun Frontend automatically enables webhooks when BigCommerce stores are connected. Because product reviews are inextricably linked to products in BigCommerce stores they are included in product webhooks. Product reviews will be synced with Shogun Frontend in the following cases:
- When a review is created and has been moved to the "approved" status. This includes reviews that are created with the "approved" status, reviews that are automatically approved as defined in the BigCommerce store settings, or are manually approved by a store administrator.
- When a review has been updated. This includes when a review is updated in the BigCommerce admin area, via the API, or by the customer who wrote the review.
- When a review has been deleted. This includes when a review is deleted in the BigCommerce admin area, via the API, or by the customer who wrote the review.
Installation
yarn add @frontend-sdk/bigcommerce-reviews
npm install @frontend-sdk/bigcommerce-reviews
Show reviews
Once all of your BigCommerce products have been synced you're ready to start using them in the Shogun Frontend IDE.
Navigate to the Sections
tab and click New Section
to start creating a new
section.
Let's start by creating a variable for use in our new component. On the right
hand side in the Variables
section click on the +
button to add a new
variable.
Give the variable a name. In this case product
would be a good descriptive
name. Select reference
as the variable type. This is going to be a reference
to content that comes from the CMS. Selecting a reference type will enable a new
dropdown called Content Type
. Select Products
as the content type.
Now you should see a list of all the fields that are available for use for a
Product
. Scroll down until you find the reviews
section and expand it.
Select all of the fields that you would like to use in your component and then
click Save
to save your progress.
Your newly created variable will now be available for use on your section in
the props
that are passed into the component.
Reviews are considered a sub-field of products and you can access reviews as a
field on the product
object when writing your component code just like you
would any other JavaScript object: product.reviews
.
A basic implementation might look like this:
// Product.jsx
const Component = ({ product }) => {
const { description, reviews, images } = product
return (
<div>
<h1>{product.page_title}</h1>
<div>
<div dangerouslySetInnerHTML={{ __html: product.description }} />
<img src={images.url_thumbnail} width={80} height={80} />
</div>
<h2>Reviews</h2>
<div>
{reviews.map((review) => (
<Review key={review.id} review={review} />
))}
</div>
</div>
)
}
// Review.jsx
const Component = ({ review }) => {
/*
* The CMS will import all reviews, regardless of their status, so we are
* ignoring reviews that are not in an approved state.
*/
if (review.status !== 'approved') return null
return (
<div>
<h3>{review.title}</h3>
<h4>
By {review.name} <small>on {review.date_reviewed}</small>
</h4>
<h5>Rating: {review.rating}</h5>
<span>{review.text}</span>
</div>
)
}
Submit a new review
Usage
Call useBigCommerceReviews()
with your site ID. Destructure the result into submitReview()
and submissionStatus
.
Create your own product review form, and in its submission handler call submitReview()
with the form's review data and the product ID.
Create your own submission success/failure component using data from submissionStatus
.
Example
import { useBigCommerceReviews } from '@frontend-sdk/bigcommerce-reviews'
const SubmitReviewPage = () => {
const { submissionStatus, submitReview } = useBigCommerceReviews(
'a1b2c3a1b2c3', // insert your Shogun Frontend site ID here
)
const initialFormData = {
title: '',
text: '',
email: '',
name: '',
rating: 0,
}
const [formData, setFormData] = useState(initialFormData)
const productId = 123
const handleChange = (event) => {
setFormData({
...formData,
[event.target.id]: event.target.value,
})
}
const handleSubmit = (event) => {
event.preventDefault()
submitReview(formData, productId)
}
return (
<div>
<form>
<div>
<label htmlFor="rating">Rating: </label>
<select id="rating" onBlur={handleChange}>
<option>Select Rating</option>
<option value={1}>1</option>
<option value={2}>2</option>
<option value={3}>3</option>
<option value={4}>4</option>
<option value={5}>5</option>
</select>
</div>
<div>
<label htmlFor="name">Name: </label>
<input id="name" onChange={handleChange} />
</div>
<div>
<label htmlFor="email">Email: </label>
<input id="email" type="email" onChange={handleChange} />
</div>
<div>
<label htmlFor="title">Review Title: </label>
<input id="title" onChange={handleChange} />
</div>
<div>
<label htmlFor="comments">Comments: </label>
<textarea id="comments" onChange={handleChange} />
</div>
<div>
<input id="button" type="submit" value="Submit review" onClick={handleSubmit}></input>
</div>
</form>
<div>
Submission response:
{submissionStatus && submissionStatus.tag && <div>tag: {submissionStatus.tag}</div>}
{submissionStatus && submissionStatus.text && <div>text: {submissionStatus.text}</div>}
</div>
</div>
)
}
Find your site ID
You can find your site ID in Shogun Frontend. Log into https://frontend.getshogun.com/ and locate your site ID in the resulting URL. In this example, https://frontend.getshogun.com/a1b2c3a1b2c3-a1b2c3a1b2c3-a1b2c3a1b2c3/pages
the site ID is a1b2c3a1b2c3-a1b2c3a1b2c3-a1b2c3a1b2c3
.
Validation of review fields
The review's fields are validated as follows:
email
: string Must be a valid email, or an empty string.name
: string Must be a string with minLength: 0 and maxLength: 255rating
: integer Must be one of 0, 1, 2, 3, 4, 5.status
: string Must be one of 'approved', 'disapproved' or 'pending'.text
: stringtitle
: string Required. Must have minLength: 0 and maxLength: 255
See BigCommerce's documentation for more detail: https://developer.bigcommerce.com/api-reference/store-management/catalog/product-reviews/createproductreview
Limitations
This integration currently has several limitations:
- No reCAPTCHA available. The "Enable reCAPTCHA on storefront?" setting in your BigCommerce admin portal does not work with this integration.
- No throttling. The "Enable Throttler" setting in your BigCommerce admin portal does not work with this integration.
- No customer validation. The "Only accept product reviews from past customers" setting in your BigCommerce admin portal does not work with this integration.
- No protection against reviews being submitted from the browser's development console.
- Very limited validation of review fields
Recommendations
- Submit all reviews with the default status (
status: 'pending'
), and manually approve them in the BigCommerce admin portal. This will provide a single layer of protection against spam reviews that are submitted through the review form you create. Note: it does not provide protection against spam reviews that are submitted from the browser's development console. - In your BigCommerce admin portal, Store Setup > Store Settings > Display, set "Auto Approve Reviews?" to
false
.