R and R

Skip to end of metadata
Go to start of metadata

Introduction

The Ratings & Reviews add-ons give your customers an easy way to provide feedback on product and content across your site, and then share that feedback with friends in their social networks. The Ratings & Reviews platform includes two add-ons:

The Ratings add-on

The Reviews add-on

The Reviews add-on is actually the Comments add-on in a 'Ratings & Reviews' operation mode and includes all the same basic functionality, including Right-to-Left localization support.

 


 

Major Features:

  • Review content by logging in with a social identity or with site credentials.
  • Ratings and reviews can be published to multiple social network feeds in one click.
  • Multiple dimensions of ratings.
  • Fully customizable design.
  • Reviews can be sorted by rating.
  • Reviews are SEO friendly and accessible to search engines.

 

The following features are shared with the Comments add-on. Click any one for a more complete explanation from our Comments documentation. 

 

Gigya uses the Comments console to implement Ratings & Reviews. In addition, the same API methods are used. For example, the Reviews add-on that is presented above is the Comments add-on in its 'Ratings & Reviews' operation mode. The operation mode is assigned by you when you Set up a new Comment category on Gigya's site. For this reason you may find the term 'Comment' used interchangeably with 'Review' in the relevant documentation and configuration pages.

Quick Start - Setup and Integration

Before you begin: Make sure that you have already set up social network application settings before you continue. For more information on how to set up an external application for use with your Gigya account, see the Setting Up External Applications in Social Networks documentation and select a specific network.

Implementation Overview

This section is a quick integration guide. Follow the steps below to integrate the Rating & Reviews add-ons with their default settings into your site.
The integration process includes three main steps:

  1. Setting up a new Comment category on Gigya's website
    Note: This step is necessary only when integrating the first instance of the Rating or Reviews add-on in your site. When integrating more instances, you can reuse the same settings and jump to step 2.
  2. Copying the generated code from Gigya's website and integrating the code into your site
  3. Integrating the Rating add-on  

Setting up a New Comment Category

Every Ratings & Reviews add-on instance belongs to a Comments category. The Comments category provides the option to define a group of Ratings & Reviews add-on instances that share the same settings. You may define one or more Comments categories for your domain. Each category may be configured to have different settings. The settings are defined on the server side and may be administrated using the Comments Setup section of Gigya's website. Follow the steps below to create a new Comments category:

  1. Go to the Comments Setup section of Gigya's website. Please make sure your are signed in. The Comments Setup page may also be accessed by clicking "Settings" in the upper menu and then "Comments Setup" in the left menu.

     
     
  2. Click the Add new comment category button:

     
  3. Fill in a new Category name and check the "Rating & Reviews" radio button:

    Note: The Category name will be used as a unique identifier for the category (aka 'categoryID').
     
  4. Click "OK". A new Comments Category instance is created. Notice the newly created row in the Comments categories table:

The JavaScript code under the "Embed code" column is the generated code that you will integrate in your site (next step). The code includes the unique categoryID that identifies the newly created category.
The "Comments Settings" button leads to an administration screen that lets you change the default settings of the Comments category. This subject is broadly explained in the Configuration and Administration section below.

Integrating the add-on Code into Your Site

The most simple and fastest way to integrate the Reviews add-on in your site is to copy the "Embed code" from the category row and paste it into the part in the <body> of your web page in which you want the add-on to appear.

 

<script src='http://cdn.gigya.com/JS/gigya.js?apiKey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N' type='text/javascript'></script>
<div id='commentsDiv'></div>
<script type='text/javascript'>
var params ={
    categoryID: 'Sports',
    streamID: '',
    version: 2,
    containerID: 'commentsDiv',
    cid:''
};
gigya.comments.showCommentsUI(params);
</script>

Unable to render {include} The included page could not be found.

The best practice though, is to cut the first line of code and move it to the <head> section of your page. This line loads Gigya's JS library file.

The outcome is:

<html>
<head>
    <script src="http://cdn.gigya.com/JS/gigya.js?apiKey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N" type="text/javascript"></script>
</head>
<body>
    <div id="commentsDiv"></div>
    <script type="text/javascript">
        var params =
        {
            categoryID: 'Sports',
            streamID: '',
            version: 2,
            containerID: 'commentsDiv',
            cid:''
        };
        
        gigya.comments.showCommentsUI(params);
    
    </script>
</body>
</html>

Unable to render {include} The included page could not be found.

The above code is of a basic web page that includes only the Comments add-on. See this code in action in the Running Example below.

Category ID

Notice the categoryID in line 12. This is the unique identifier for the Comments category that you have defined in the previous step.

Stream ID

Notice the streamID in line 13. The streamID identifies a stream of reviews within a Comments category. The ID is now empty, meaning that we have a single stream with an empty identifier. Two Comments add-on instances that share the same categoryID and streamID will show the same reviews.
To create several instances of Comments add-on that belong to the same category, copy the same code to different places in your site where you wish to insert the add-on. In each place, assign a different identifier (string) to the streamID. We suggest you use the permalink as the streamID. Note: the streamID is limited to 150 characters and is case sensitive.

Integrating the Ratings add-on

Adding the Ratings add-on is simple, just add the following lines of code to the location in your page where you wish to show the add-on:

<div id='ratingsDiv'></div>

<script type='text/javascript'>

var ratingsParams ={
    categoryID: 'Sports',  // Comments category ID (from Comments Setup page)
    streamID: '',
    containerID: 'ratingsDiv', // <div> ID  in which to present the add-on
    linkedCommentsUI: 'commentsDiv' // link the Ratings add-on to the Comments add-on. 
};

gigya.comments.showRatingUI(ratingsParams);

</script>

Code Explanation:

  • Line 1 - defines the <div> in which to place the add-on.
  • Line 9 - call the comments.showRatingUI API method, which presents the Rating add-on.
  • Line 3-8 - showRatingUI method parameters:
    • categoryID - this is the same Category ID from previous steps.
    • streamID - this is the same Stream ID from previous steps.
    • containerID - The ID of the <div> defined in line 1.
    • linkedCommentsUI - this parameter links the Rating add-on to the Comments (Reviews) add-on, which is located on the same page. The value is <div> ID in which the Comments add-on is presented. This way the '# reviews' link on the Rating add-on becomes an anchor to the Comments add-on on the page.

Running Example

 

 

 Please find the example code in the Ratings & Reviews demo page.

Configuration and Administration

If you go back to the Comments Setup page, in the Comments category row that you have created, you will see a "Comments Settings" button. Clicking this button leads to the Comments Settings page. This page is an administration screen that lets you change the default settings of the Comments category.

 

You may change the settings as you choose and then save them by clicking the "Save changes" button at the bottom of the page. The changes are saved in Gigya's database (server side). No coding changes are required. The change will take effect immediately. For a page that is already loaded, refresh the page and you will see the change.

The available configuration options in this page:

Changing to 'Read Only'

The 'Status' property is enabled by default, meaning that users are able to submit reviews.
If you change the Status to 'Read only', users will only be able to read reviews. Graphically, the 'Post your review' canvas is not displayed.

 

Moderation

Gigya's Ratings & Reviews service supports moderation administration. This section of the Comments Settings page includes moderation settings, including notification email, moderation mode, and more. Read more in the Comments (and Ratings) Moderation dedicated guide.

 

Social Network Publishing

The 'Share to social network' check box is checked by default, meaning that the reviews submitted by the users are shared to the selected social network or networks.
If you change the check box to unchecked, the users will be able to submit reviews, but the reviews will not be shared to social networks.

Layout Customization

This section allows you to change a few aspects of the Reviews add-on layout settings:

Pagination

Pagination refers to dividing the comments into pages. The default is a display of 25 comments per page, but you may choose to change the number of comments per page using the drop-down menu.

Comment Box Location

The Comment box refers to the 'Post your review' canvas. By default it is located below the reviews, at the bottom of the add-on. You may change this by checking the 'Top' radio button. As a result the canvas will appear above the reviews, at the top of the add-on.

Other Settings

This section allows you to change the default settings of:

  • Comments threading
  • Replies default view
  • Enabling Google Analytics Social Data Hub integration
  • Maximum comment length
  • Displaying Facebook comments
  • Allowing users to delete their own comments
  • Enabling voting on comments, including allowing negative voting and showing separate counter for negative voting
  • Comment sorting, including different sorting options and allowing user sorting. 
  • Enabling rich text formatting

 

Comments Threading

By default comment threading is allowed, meaning that comments on reviews are allowed and displayed in a nested manner. If you prefer not to allow comments threading, press the 'No' radio button. You may choose the depth of the threading, from 1 to 5, using the drop-down menu. The default threading depth is 2. By default the comments on reviews are collapsed and the user may view them by clicking the Comments link. You may change the default to 'Expanded', by checking the corresponding radio button.

The following screenshot presents an example of a review with two comments in an expanded view mode:

 

By clicking the 2 Comments link the comments will collapse. Note - the threading depth in this example is two, so one cannot reply to a comment.

Replies Default View

You can decide whether the replies to the comments will be displayed in expanded or collapsed view.

Google Analytics Social Data Hub Integration

Gigya supports integration with Google Analytics Social Data Hub. By selecting the 'Yes' radio button, you allow Gigya to publish your comments streams to Google Analytics via the PubSubHubbub (PSHB) protocol.

Displaying Facebook Comments

You can choose to display the Facebook comments stream as part of the Reviews add-on. The comments from Facebook are marked 'Via Facebook':

 

Note: In order to be able to view Facebook comments, the Facebook privacy settings regarding posts should be set to 'Everyone'.

Enabling Voting on Reviews

Determine whether to make voting on reviews available for users. "Allow negative voting" determines whether users will be able to vote negatively (thumbs down) on reviews. If these check-boxes are checked, the Comments add-on shows a set voting icons next to each review:

Sorting Comments

There are few options for sorting the reviews in the Reviews add-on. By default the reviews are sorted by the rating value, the first comment is the one that gave highest rating. You may change the default to one of the following options:

  • Most recent on top - the reviews are sorted by the timestamp of the post. The first review is the latest one.
  • Most recent on bottom - the reviews are sorted by the timestamp of the post. The first review is the first created (oldest).
  • Most relevant on top - the reviews are sorted by timestamp of the reply.  
  • Top rated on top - the reviews are sorted by the overall rating value. The first review is the one that has the highest rating.
  • Top rated on bottom - the reviews are sorted by the overall rating value. The first review is the one that has the lowest rating.
  • Most voted on top - the first review is the one that has the highest votes. The reviews are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread.
  • Most voted on bottom - the first review is the one that has the lowest votes. The reviews are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread.

Starting from Comments version 2, you can also allow users to sort the comments in a different way than as it was preset by the site. The sort options are the displayed in a drop-down menu, and they are the same; the user can select to sort the comments according to most recent on top, most recent on bottom, most relevant on top, most voted on top, or most voted on bottom. Once a new sort is selected by the user, the comments are reloaded according to the new sort. 

Allow Users to Delete their own Comments

When you check the checkbox, an "X" will appear in the top right-hand corner of comments of the logged-in user, allowing the user to delete his own comments:

Enable Rich Text Formatting

When you select this check box, the comments users are able to perform text formatting on all new comments. A formatting toolbar is displayed, and when a user clicks on any of the format buttons, the format of the selected text in the comment is changed accordingly.

This feature is available from Comments version 2

Rating & Reviews Settings

Review Buttons

When using the Ratings and Reviews add-on, choose whether to show or hide the ratings buttons (stars), and whether it is required for users to post their rating with their review. If the ratings buttons are required, and you are using direct API calls then the 'ratings' parameter in comments.postComment method is required.

Review Title

When using the Ratings and Reviews add-on, choose whether to show or hide the review title, and whether it is required for users to post a review title with their review. If the review title is required, and you are using direct API calls, then the 'commentTitle' parameter in comments.postComment method is required.

Comment Body

When using the Ratings and Reviews add-on, choose whether to show or hide the comment body, and whether it is required for users to post a comment body with their review. 

Ratings Dimensions

 

The Ratings and Reviews add-on allows more than one dimension of ratings within one piece of content in addition to the overall rating. For example, you can define "shopping", "sport", and "customer services" dimensions, and each will have their own ratings. 

Add a New Dimension

Click the "Add New Dimension" button and insert a unique ID and a name (label) for the ratings dimension. Then click "Submit":

 

In a similar fashion, you may add more dimensions. The new dimensions will be displayed in the table: 

 

The Ratings & Reviews add-on will then be displayed with the overall rating, and by clicking the dimensions drop-down, you will be able to see all the add-on's ratings dimensions:

UI Customizations

We provide several levels of customization for the Rating add-on UI:

You are welcome to consult Gigya's support team to guide you through advanced UI customizations. You can contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

HTML Elements Style (CSS)

Any element on the add-on that has an ID can be overridden with supported style attributes. There are dozens of elements on the add-on. You may use Firebug to identify an HTML element on the add-on and assign a new style to it. Please make sure to use the add-on's container <div> ID when assigning style, so it will not affect other elements on the page.
For example:

<style> #commentsDiv .gig-comments-button-post {color:Yellow;background-color:black} </style>

Templates

A template is a layout definition for a group of related graphics elements in the add-on. The add-on includes a customizable template called ratingTemplate. You may assign the template with an HTML string that redefines the Rating add-on's graphic layout. The HTML string include the following placeholders: $stars, $readReviewsLink, $addReviewButton, $write_a_review and $review_summary (sets the title).

There is also a new template format, which uses HTML classes instead of the $ placeholders:
  • gig-rating-stars - the average rating stars
  • gig-rating-readReviewsLink - the read reviews 
  • gig-rating-writeYourReview - the write review
  • gig-rating-dimensions - the dimensions box is the dimension titles plus the stars
 
Example template:

 

<div>
    Overall rating:
<div>
<div class="gig-rating-dimensions"></div>

 

Importing Rating and Reviews Systems

Gigya supports importing third-party rating and reviews systems. If you wish to migrate to Gigya's rating and reviews system, you can import your existing rating and reviews to Gigya and display them on your site. For this operation, please contact your Customer Services manager. 

Search Engine Optimization (SEO) Support

This section provides instructions on how to make the comments in your Comments add-on searchable by the main search engines in order to add valuable SEO data to your site. As search engines index only static data of your site.

It is difficult to make them index dynamic data. This includes the comments data. The comments data is kept on Gigya's server and is requested dynamically. The search engines do not see and do not index the comments data. To solve this issue Gigya provides a static HTML format of the comments with an up-to-date content that is readable by search engines and can be indexed.

To take advantage of this, please follow the steps below:

  1. Detect the Search Engine Crawlers: Find out whether the page is viewed by a search engine spider (bot). Identify the search engine using the HTTP_USER_AGENT field. You may find a PHP example here.
  2. Inject HTML Comments data: If a search engine is identified, load the HTML content of the comments instance by setting the dataFormat parameter of comments.getComments to 'html':

 

 

  • No labels