Table of contents
- 1. Introduction
- 1.1. The Rating Plugin
- 1.2. The Reviews Plugin
- 1.3. Major Features
- 2. Quick Start - Setup and Integration
- 2.1. Setting up a New Comment Category
- 2.2. Integrating the Plugin Code into Your Site
- 2.2.1. Category ID
- 2.2.2. Stream ID
- 2.3. Integrating the Rating Plugin
- 2.3.1. Code Explanation:
- 3. Running Example
- 4. Configuration and Administration
- 4.1. Changing to 'Read Only'
- 4.2. Moderation
- 4.3. Social Network Publishing
- 4.4. Layout Customization
- 4.4.1. Pagination
- 4.4.2. Comment Box Location
- 4.5. Other Settings
- 4.5.1. Comments Threading
- 4.5.2. Replies Default View
- 4.5.3. Google Analytics Social Data Hub Integration
- 4.5.4. Displaying Facebook Comments
- 4.5.5. Enabling Voting on Reviews
- 4.5.6. Sorting Comments
- 4.5.7. Allow Users to Delete their own Comments
- 4.6. Rating & Reviews Settings
- 4.6.1. Review Title
- 4.6.2. Comment Body
- 5. UI Customizations
- 5.1. HTML Elements Style (CSS)
- 5.2. Templates
- 6. Importing Rating and Reviews Systems
- 7. Search Engine Optimization (SEO) Support
Introduction
The Rating & Reviews plugins 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 Rating & Reviews platform includes two plugins:
The Rating Plugin
The Reviews Plugin
The Reviews plugin is actually the Comments plugin in a 'Rating & Reviews' operation mode.
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
- Fully customizable design
- Reviews can be sorted by rating
- Reviews are SEO friendly and accessible to search engines
For this reason you may find the term 'Comment' instead of 'Review' in the relevant documentation and configuration pages.
Quick Start - Setup and Integration
This section is a quick integration guide. Follow the steps below to integrate the Rating & Reviews plugins with their default settings into your site.
The integration process includes three main steps:
- 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 plugin in your site. When integrating more instances, you can reuse the same settings and jump to step 2. - Copying the generated code from Gigya's website and integrating the code into your site
- Integrating the Rating plugin
Setting up a New Comment Category
Every Rating & Reviews plugin instance belongs to a Comments category. The Comments category provides the option to define a group of Rating & Reviews plugin 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:
- 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.
- Click the Add new comment category button:
- 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').
- 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 Plugin Code into Your Site
The most simple and fastest way to integrate the Reviews plugin 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 plugin to appear.
<script src='http://cdn.gigya.com/JS/socialize.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: '',
containerID: 'commentsDiv',
cid:''
}
gigya.socialize.showCommentsUI(params);
</script>
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/socialize.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: '',
containerID: 'commentsDiv',
cid:''
}
gigya.socialize.showCommentsUI(params);
</script>
</body>
</html> The above code is of a basic web page that includes only the Comments plugin. 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 plugin instances that share the same categoryID and streamID will show the same reviews.
To create several instances of Comments plugins that belong to the same category, copy the same code to different places in your site where you wish to insert the plugin. 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 Rating Plugin
Adding the Ratings plugin is simple, just add the following lines of code to the location in your page where you wish to show the plugin:
<div id='ratingDiv'></div>
<script type='text/javascript'>
var ratingsParams ={
categoryID: 'Sports', // Comments category ID (from Comments Setup page)
streamID: '',
containerID: 'ratingDiv', // <div> ID in which to present the plugin
linkedCommentsUI: 'commentsDiv' // link the Ratings plugin to the Comments plugin.
}
gigya.socialize.showRatingUI(ratingsParams);
</script> Code Explanation:
- Line 1 - defines the <div> in which to place the plugin
- Line 9 - call the socialize.showRatingUI API method, which presents the Rating plugin.
- 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 plugin to the Comments (Reviews) plugin, which is located on the same page. The value is <div> ID in which the Comments plugin is presented. This way the '# reviews' link on the Rating plugin becomes an anchor to the Comments plugin on the page.
Running Example
Please find the example code in the Rating & 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 Rating & 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 plugin 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 plugin. 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 plugin.
Other Settings
This section allows you to change the default settings of:
- Comments threading
- Replies default view
- Enabling Google Analytics Social Data Hub integration
- Displaying Facebook comments
- Enabling voting on comments
- Sort comment by
- Allow users to delete their own comments
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 plugin. The comments from Facebook are marked 'Via Facebook':
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 Plugin shows a set voting icons next to each review: 
Sorting Comments
There are few options for sorting the reviews in the Reviews plugin. 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:
- Top rated on bottom - the reviews are sorted by the rating value. The first review is the one that has the lowest rating.
- 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 the overall votes value (positive votes minus negative votes) of the root comment in each thread. The first review is the one that has highest votes.
Allow Users to Delete their own Comments
Rating & Reviews Settings
Ratings Buttons
When using the Ratings and Reviews plugin, 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 plugin, 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 plugin, choose whether to show or hide the comment body, and whether it is required for users to post a comment body with their review.
UI Customizations
We provide several levels of customization for the Rating plugin's UI:
- HTML Elements Style
- Templates - redefining graphic layout.
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 elements on the plugin that has an ID can be overridden with supported style attributes. There are dozens of elements on the plugin. You may use Firebug to identify an HTML element on the plugin and assign a new style to it. Please make sure to use the plugin's container <div> ID when assigning style, so it will not affect other elements on the page.
For example:
<style> #commentsDiv .gig-button-post-text {color:Yellow;background-color:black} </style>
Templates
A template is a layout definition for a group of related graphics elements in the plugin. The plugin includes a customizable template called ratingTemplate. You may assign the template with an HTML string that redefines the Rating plugin's graphic layout. The HTML string include the following placeholders: $stars, $readReviewsLink, $addReviewButton.
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. You will need to provide an XML file with your comments, according to this XML schema definition.
Search Engine Optimization (SEO) Support
This section provides instructions on how to make the comments in your Comments plugin searchable by the main search engines, and by that adding SEO value to users. As you know search engines index only static data in 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:
- 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.
- 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':
Comments