Skip to main content

JavaScript Reference Guide

  • Updated

PowerReviews uses a JavaScript library to render user interfaces that display and collect content about your products and/or services. This JavaScript library is referred to as the Content Engine.

This article contains the following sections:

 

Service Information

As a third-party service, PowerReviews recognizes the importance of providing highly performant software. The Content Engine is served on PowerReviews' hosting platform - a Cloudfront-based Content Delivery Network (CDN). A CDN is a network of servers located throughout the world that ensure the Content Engine JavaScript is delivered quickly and reliably, regardless of where your customers are located. The size of the Engine is roughly 200kb. By hosting the Content Engine on a CDN, PowerReviews can deliver new features and updates that don’t require any changes on how the JavaScript is integrated and implemented on your website.

Additionally, the Content Engine loads JavaScript asynchronously to maximize your page load speed. This means that your browser can load other elements while the Content Engine loads the JavaScript on your webpages. It also ensures that the remainder of the page is unaffected should the Content Engine or corresponding API become unavailable.

 

Initializing the Content Engine

The Content Engine is a JavaScript library that gives you the ability to render various user interfaces that display and collect content from PowerReviews. You should source the Content Engine within the <body> tags of your page.

<script src="https://ui.powerreviews.com/stable/4.1/ui.js" async></script>

 

The Content Engine API

The pwr("render") calls the API on page load. This product configuration object, or array of configuration objects, renders PowerReviews content on your webpage.

The pwr("render") can only be called once per page load. PowerReviews batches UI rendering into a single call, so requests to the PowerReviews API are also batched into as few calls as possible. This ensures optimal performance on your page. If a page loads via infinite scroll (or other subsequent calls), you are then able to make additional render calls at that time.

 

The Product Configuration Object Model

The Product Configuration Object Model contains identifying information necessary to find content for your products, as well as instructions on where to inject PowerReviews content into your webpage.

Key Description Required?
api_key Your PowerReviews API Key Yes
merchant_id Your Merchant ID Yes
merchant_group_id Your Merchant Group ID. Yes
locale The content locale. Yes
page_id The unique identifier of the page or product you'd like to display content for. Yes
name The product name. Yes
image_url A public-facing URL to an image of the product. Yes
description A description of the product. Yes
category_name The PowerReviews-formatted category hierarchy of the product. For example, Shoes > Women's Shoes > Pumps. Yes
manufacturer_id The manufacturer id for the product. Yes, for syndication.
upc The 13-digit UPC for the product. Yes, for syndication.
brand_name The brand of the product. Yes, for syndication.
price The price of the product. No
in_stock If the product is in stock. This is a true/false key. No
url The URL of the product detail page on your website. This key shouldn't contain spaces. Yes
on_read_reviews_click A mechanism to attach a callback function to the Read Reviews link. No
on_write_review_click A mechanism to attach a callback function to the Write A Review link. No
on_view_answers_click A mechanism to attach a callback function to the View Answers link. No
on_ask_question_click A mechanism to attach a callback function to the Ask A Question link. No
review_wrapper_url The full URL path to your Write-a-Review page. If you're not using PowerReviews' Follow-Up Email, this key is required.
style_sheet The full URL path to your PowerReviews CSS theme CSS. No
components An object that contains mappins of PowerReviews content keys to DOM element IDs where the content should be injected. Yes
on_render A callback function that's triggered when components render. For more information, see Callbacks.  No
on_submit A callback function that's triggered when a Content Collection interface is submitted. For more information, see Callbacks. No
on_back_to_top_click A callback function that's triggered when a user clicks the back to top link. For more information, see Callbacks. No
merchant_user_email The email address for the customer writing the review. No
merchant_user_id The unique identifier for the customer writing the review. Typically, this is your internal user ID or customer ID, and can be passed over to the Write-a-Review form. No
source Indicates whether the user has arrived at the Write-a-Review page from a Web page or email message link. No
enable_content_collection_modal Set to 'false' if the modal is not being used to allow for addiitonal performance enhancement. No

 

The Components Object Model

The Components Object Model defines what PowerReviews content you'd like to render, and where to render it to. The keys of the properties within the Components Object correlate to the content you'd like to render for a product. Their values correspond to the ID of the container HTML element where the content should be rendered.

The following table contains the various types of content that the Content Engine can render:

 

Displaying Reviews

Key Description
CategorySnippet A small UI that displays the aggregate rating and review count - typically used on category pages.
ReviewSnippet A small UI that displays the aggregate rating, review count, and percentage of recommendations for a product - typically used on PDP pages.
ReviewDisplay The comprehensive Review Display component. Contains the Review Image Display, the Review Display Snapshot, and the Review List.
ReviewSnapshot An interface that displays the aggregate rating, a distribution of review ratings, and aggregate tag information for a product.
ReviewList An interface that displays a list of detailed individual reviews

 

Displaying Questions & Answers

Key Description
QuestionSnippet A small UI that displays the aggregate number of questions, as well as link to ask a question.
QuestionDisplay A UI that displays all questions and answers for a product, and also provides the ability for consumers to ask their own questions and answer others' questions.

 

Displaying Review Images

Key Description
ReviewImageSnippet A small UI that displays a short list of review images.
ReviewImageDisplay An interface that displays all images for a given product.

 

Collecting Reviews, Questions, and Answers

Key Description
Write A dynamic UI that intelligently displays the proper form for collecting content. You should only use the Write component on a single webpage. Typically this page is called the Write-a-Review Host Page. Calls to action to Write-a-Review, Review Purchases, Write-a-Question, or Write-an-Answer within other UIs (the Review Display, Question Display, and Follow-Up Emails) will redirect to this page.

 

Add to Cart

Key Description
AddToCart Built in tracking to help measure the influence of the PowerReviews solution on the behavior of your consumers by observing when consumers look at the content display and add that item to their cart. The value of this should be the ID of a container your current Add To Cart button resides within.


Note: Programmatically manipulating PowerReviews content creates significant risk. If there is behavior that you want to implement, but can't accomplish through the render () method, contact PowerReviews Technical Support.

 

Callbacks

You can attach Callback functions to milestones within the PowerReviews component lifecycle.

 

on_render(config, data)

When the Product Configuration Object contains a function assigned to the on_render property (a callback function), that callback function is called once for each item in the components map when the component renders.

Example:

<script>
 window.pwr = window.pwr || function () {
   (pwr.q = pwr.q || []).push(arguments); 
 };
 pwr("render", {
    api_key: '<API Key>',
    locale: '<locale>',
    merchant_group_id: '<MGID>',
    merchant_id: '<Merchant ID>',
    page_id: '<PageID>',
    review_wrapper_url: 'http://yoursite.com/write-a-review/?pr_page_id=__PAGE_ID__',
      on_render: function(config, data) {
        console.log(config);
        console.log(data);
    },
    components: {
      ReviewSnippet: 'pr-reviewsnippet',
      ReviewImageSnippet: 'pr-imagesnippet',
      ReviewDisplay: 'pr-reviewdisplay'
    }
 });
</script>

Two parameters are included in the callback function - config and data.

The config object contains the key of the component that was rendered, as well as the page_id of the product used in that component. Using this data, you can identify the rendered component. The data parameter includes high-level aggregate data related to the product and component.

For Review-related components, this object includes the total number of reviews (review_count) and the aggregate rating (aggregate_rating). For Question-related components, this object contains the number of questions (question_count).

 

on_submit(config, data)

The on_submit callback works similarly to the on_render() callback, but is specific to the Content Collection interfaces: the Write-a-Review, Write-a-Question, Write-an-Answer, and Seller Ratings interfaces.

When a Content Collection product configuration object contains a function assigned to the on_submit property (a callback function), that callback function is called for the corresponding component when a user submits data.

Example:

<script>
 window.pwr = window.pwr || function () {
   (pwr.q = pwr.q || []).push(arguments); 
 };
 pwr("render", {
    api_key: '<API Key>',
    locale: '<locale>',
    merchant_group_id: '<MGID>',
    merchant_id: '<Merchant ID>',
    page_id: '<PageID>',
    review_wrapper_url: 'http://ui.powerreviews.com/stable/standalone.4.0.html?pageId=~~~PAGE_ID~~~',
      on_render: function(config, data) {
      console.log('A Content Collection UI was rendered', config, data);
      },
      on_submit: function(config, data) {
      console.log('User input was submitted', config, data);
      },
      components: {
      Write: 'pr-write'
 });
</script>

Two parameters are included in the callback function - config and data.

The config object contains the key of the component that was rendered, as well as the page_id of the product used in that component. Using this data you can identify the rendered component. The data parameter includes an array called fields. This array contains all of the inputs the user provides.

 

on_back_to_top_click (config, data)

You can assign a function to the on_back_to_top_click property to attach a custom click event handler to the Back to Top button that appears on the Review Display. You can use this event handler to add custom behavior to this button, like specifying a custom scroll-to-top target.

Example:

<script>
 window.pwr = window.pwr || function () {
   (pwr.q = pwr.q || []).push(arguments); 
 };
 pwr("render", {
    api_key: '<API Key>',
    locale: '<locale>',
    merchant_group_id: '<MGID>',
    merchant_id: '<Merchant ID>',
    page_id: '<PageID>',
    review_wrapper_url: 'http://ui.powerreviews.com/stable/standalone.4.0.html?pageId=~~~PAGE_ID~~~',
    on_back_to_top_click: function() {
      alert(‘Back to top has been clicked!’)
  },
  components: {
    Write: 'pr-write'
 });
</script>

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Return to top