@frontend-sdk/bigcommerce-reviews v0.25.1

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: 255
• rating: integer Must be one of 0, 1, 2, 3, 4, 5.
• status: string Must be one of 'approved', 'disapproved' or 'pending'.
• text: string
• title: 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.