Comments

Skip to end of metadata
Go to start of metadata

Introduction

Gigya's Comments add-on enables site users to post comments and have discussions about published content on the site.

This guide describes the Comments add-on, walks you through add-on setup and integration, and serves as a reference document for the configuration and customization options.

Gigya now offers a new, improved version of the comments add-on, version 2, which differs from the original version in the following ways:

  • Newer, better visual layout
  • Sharing comments to social networks
  • Support for rich text editor
  • Allow user sorting of comments
  • Support for comment highlighting
  • Allow logged-in users to post anonymous comments or reviews
  • In-line tagging of commenters
  • Localization support for right-to-left languages
  • Responsive design
  • Support for custom texts

Using the new Comments add-on version 2 is simple; just add the version parameter to the params of the comments.showCommentsUI method, and set it to 2:

var params =  { 
    categoryID: 7623701,
    streamID: '',
    containerID: 'commentsDiv',
    version: 2
};

 

This guide also includes an explanation on how to make the comments in your Comments add-on searchable using  Search Engine Optimization (SEO) Support.

  • If you wish to use the add-on for R&R, please follow the designated guide.

How it Works

The add-on presents:

  1. A "Write a comment" canvas. The look of the canvas depends on whether the user is logged in.
  2. A "Comments" stream.

Layout When User is Logged Out

When a user clicks inside the "Write a comment" canvas, it expands and displays the "Post" button as well as a grayed-out sharing panel which contains check boxes for several social networks. If rich text formatting and/or media have been enabled, the appropriate buttons for these features are displayed on the top right corner of the text box (or top left, if the add-on is displayed in RTL mode):

 

If a user tries to post a comment when they are not logged in, the user is prompted to either log in or post a comment as a guest:

 

Note: By default, clicking "Post" prompts the user to log in and does not offer the "As Guest" option. You can configure the comments add-on to enable anonymous (guest) comments: see  Adding Guest Login.

 

A Login Bar can be displayed above the text box by setting the showLoginBar  parameter to true in comments.showCommentsUI. If guest login has been enabled, the Login Bar displays an extra button for logging in as a guest:

The Share panel under the text box allows the user to choose a social network to share the comment to. For a user who is not logged in, clicking one of the check boxes in the Share Panel opens a login popup, where the user can connect to the selected social network. Once the user is logged in to the network, the appropriate check box is checked, and subsequent comments posted will also be shared to the specified social network(s).

 

Layout When User is Logged In


 

In the logged-in state, the "Write a comment" canvas includes:

  • The user's screen name and profile picture. Note that the screen name is taken from profile.nickname rather than profile.username.
  • A Commenting input box.
  • A "Follow replies to my comments" link that once clicked notifies the user when someone replies to his comments. 
  • A collapsed Share panel (check boxes with social network icons) - provides an option to share a posted comment to social networks. 
  • A plus sign that once clicked offers more options of sharing destinations.

Major Features

  • The add-on provides an integrated social login:
    • Through a social network account. Such case may initiate a user to sign-up to your site.
    • Using the site credentials.
    • As a guest user.
  • The Comments add-on graphic design is highly customizable (read more in the UI Customizations section below).
  • Comment threads - replies to a comment.
  • Export current comments through RSS/XML format.
  • Following replies to comments.
  • Importing 3rd party commenting systems.
  • Moderation.
  • Highlighting comments.
  • Rich text editor.
  • Server side administration: use the Comments Setup page on Gigya's website to define categories for comments and customize each comment category settings.
  • Sharing comments to social networks.
  • Support multiple comments streams per category .
  • Supports publishing a posted comment to one or more social network destinations. This enables users to share their comments with their social networks friends.
  • Subscribing to comments streams by email.


 

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 guide will help you quickly integrate Gigya's Comments Add-on into your site, with their default settings.

This guide assumes you have already set up a site in the Gigya Dashboard with a valid API Key and that you have RaaS or Social Login enabled for that key and that the gigya.js Web SDK is included on your site.

 

Comments Within A Site-Group

In a site-group, comments work as they do otherwise. Comments are not shareable between multiple API keys, so each child site that uses comments must have their own comments configuration.

 

Integration

The integration process includes two broad stages:

  1. Setting up a New Comment Category on Gigya's website 
    Note: This step is necessary only when integrating the initial instance of the Comments Add-on on your site. When integrating more instances, you can reuse the same settings and jump to Stage 2.
  2. Copying the generated code from Gigya's website and integrating the code into your site 

Setting up a New Comment Category

Every Comments Add-on instance belongs to a Comments Category. The Comments Category provides the option to define a group of Comments 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 in the left menu.
     

     
  2. Click the Add new comment category button:
     
     
  3. Fill in a new Category Name and select the Comments radio button:
        
     
  4. Click OK. A new Comments Category instance is created. Notice the newly created row in the Comments categories table:
     
    The JavaScript code under "Embed code" column is the generated code that you will integrate in your site (next step). The code includes a generated 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 simplest and fasted way to integrate the Comments Add-on in your site is to copy the "Embed code" from the category row and paste it into the spot in the part of your web page in which you want the Add-on to appear.

 

<script src="http://cdn.gigya.com/js/gigya.js?apiKey=YOUR-APIKEY-HERE" 
type="text/javascript"></script>
<div id="commentsDiv"></div>
<script type="text/javascript">
    var params =
    {
        categoryID: 'Developers Public Comments',
        streamID: 'streamid',
        version: 2,
        containerID: 'commentsDiv',
        cid:'',
        enabledShareProviders: 'facebook,twitter,linkedin'
    };
    gigya.comments.showCommentsUI(params);
</script> 

 

The best practice, though, is to cut the first line of code and move it to the section of your page. This line loads Gigya's Web SDK.

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: 7623701,
            streamID: '',
            version: 2,
            containerID: 'commentsDiv',
            cid:'',
            enabledShareProviders: 'facebook,twitter,linkedin'
        };

        gigya.comments.showCommentsUI(params);
    </script>
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API Key.
  • If you are using https, be sure to further adjust the JS API url to: https://cdns.gigya.com/js/gigya.js?apikey=<Your_API_Key>.

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 ID was generated by Gigya and is a 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 comments 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 comments.
To create several instances of Comments Add-ons that belong to the same category, copy the same code to different spots in your site where you wish to insert the Add-on. In each spot, assign a different identifier (string) to the streamID. We suggest using the permalink as the streamID. Note: streamID is limited to 150 characters and is case-sensitive.

Running Example

 

Comments Add-on Demo

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 are:

Changing to 'Read Only'

The 'Status' property is 'Enabled' by default, meaning that users are able to submit comments.
If you change the Status to 'Read only', users will only be able to read comments. Graphically, the 'Post a new comment' canvas is not displayed.

Moderation

Gigya's commenting 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 Moderation dedicated  guide .

Notifications

When Moderation is enabled, the moderator(s) will receive an email whenever a comment is posted. This includes Rejected and Flagged comments.

When comments reach the specified Flag threshold, they are moved into the Flagged que within the Moderator panel.

If you enabled Allow users to delete their comments, once a comment is deleted by the user, it ceases to exist within the Moderation panel.

Moderator Comments

In this section you can also choose how moderator commenter names and photos will appear in comment streams when they reply to comments. Read more  in the  Comments Moderation dedicated guide .

Adding and Changing Moderators

You can add to or modify the moderators for your site by clicking the Moderator tab in the Comments section of the left-hand navigation menu.


 

On the Moderator page you are able to add and remove moderators. There is also a link directly to the Moderators Panel.



Highlighted Comments 

Comment highlighting allows you to make certain comments or reviews in your site stand out from the rest using colors and icons.

There are three major uses of comment highlighting: 

  1. You may want replies made by comment moderators to be easily recognized. In that case, use Highlight Moderators.
  2. Similarly, you may want comments made by certain special users, such as site staff, to be easily recognized. In that case, use Highlight User Groups. You can use one or more of the pre-defined groups or define new ones.
  3. You may want moderators to select some comments manually for highlighting, e.g. to mark well-written comments as "Editor's pick". In that case, use Highlight Specific Comments.

To set up these different types of highlighting, see the appropriate sections below.

 

Notes:

  1. Only comments submitted by logged-in users can be highlighted.
  2. Highlighting and disabling of highlighting for groups of users only affect future comments posted by the users.

Highlight Moderators

Comments  posted by moderators can include a unique visual indication, as previewed in the Settings page:

The status is "On" by default, meaning that highlighting of moderator comments is enabled.

To edit the settings of the Moderators group, click the edit icon under the Settings column. This will open the Edit Group Properties dialog box.

In the Edit Group Properties dialog box, you can:

  • Choose not to show the "Moderator" badge, in which case only the moderator name will appear (this is the default behavior).
  • Change the text that will appear in the badge, by checking the "Customize" box and entering a new name in the text box instead of the default "Moderator".
  • Change the badge color, by choosing a different color from the drop-down menu. 
  • Choose not to color the commenter's name, or to change the default color, by choosing a different color from the drop-down menu.

Any changes you make are shown to you in the "Preview" section.

The Comments add-on will display the moderator comments according to the settings you defined here:

In this case the text of the "Moderator" badge has been customized, and changed to "hello". The color of the "hello" badge and the color of moderator's name have not been changed.

If you chose to show the "Moderator" badge (either customized or not), the badge will be the first to appear (i.e. before any other badge such as Staff, Expert, Journalist, etc.).

Highlight User Groups

 If you set up highlighting for user groups, comments posted by users who belong to specified groups will include a unique visual indication, as previewed in the Settings page.

To assign users to groups, use the Comments Moderation Page.

 

Pre-Defined Custom User Groups:

Three user groups are pre-defined for you: Staff, Expert and Journalist. However, comment highlighting is not enabled for any of them by default. If you choose to use any of these groups, you need to change the Status of the group to "On" (as well as assign users to the group).

To delete a group, click the "X" icon under the Settings column of that group.

To edit the settings of a group, click the edit icon under the Settings column of that group. This will open the Edit Group Properties dialog box.

In the Edit Group Properties dialog box, you can:

  • Choose not to show the "Moderator" badge, in which case only the moderator name will appear (this is the default behavior).
  • Change the text that will appear in the badge, by checking the "Customize" box and entering a new name in the text box instead of the default "Moderator".
  • Change the badge color, by choosing a different color from the drop-down menu. 
  • Choose not to color the commenter's name, or to change the default color, by choosing a different color from the drop-down menu.

Any changes you make are shown to you in the "Preview" section.

 

Adding a New Group:

To add a new custom user group, click the "Add New Group" button. This opens the Add New Group dialog box, where you can name the group, specify whether to show a badge, select a badge color and select a color to apply to the commenter's name. Click Create to add the group.

The Comments add-on will display the custom group comments according to the settings you defined here.

In this example, the user belongs to two groups - Journalist and Staff. Each has their own badge and color. Both badges are displayed.

If the user is highlighted, the highlighting badges are also shown in the post box.

Highlight Comments

 This option allows you to apply highlighting to specific comments that are selected manually by a moderator using the Comments Moderation Page. The visual indication that will be applied to these comments is previewed in the Settings page.

There is one pre-defined group for comments: "Editor's Pick". Its status is "Off" by default. Change the Status indicator to "On" to enable highlighting of comments that have been marked as "Editor's Pick" by a moderator.

  • To delete this group, click the "X" icon in the "Settings" column for this group.
  • To edit the settings for "Editor's Pick" or for any new group that you have created, click the "Edit" icon under the Settings column for that group. This will open the Edit Group Properties dialog box.

 

In the Edit Group Properties dialog box, you can:

  • Choose not to show the "Editor's Pick" badge, in which case only the background will appear.
  • Change the text that will appear in the badge, by checking the "Customize" box and entering a new name in the text box instead of the default "Editor's Pick".
  • Change the default image, by entering a new image URL (which must end in .jpg, .jpeg, .png, or .gif).
  • Change the badge color, by choosing a different color from the drop-down menu. 
  • Choose not to color the background, or to change the default background color, by choosing a different color from the drop-down menu.

Any changes you make are shown to you in the "Preview" section.

 

To add new comment groups, click Add New Group. This will open the following dialog box:

  • Enter a group name, decide whether to show a badge, and if chosen, enter the text and choose the color of the text badge.
  • You can also change the badge image, by entering a new image URL (which must end in .jpg, .jpeg, .png, or .gif).
  • Then decide whether to color the background , and pick a color from the drop-down menu.
  • Click "Create", and the new group will be added to the table. 

User Login

This section controls the login UI, which is included in the "Write a Comment" canvas. If a user tries to post a comment when they are not logged in, a login prompt appears:

 

In addition, it is possible to display a Login bar in the add-on by setting the showLoginBar  parameter in comments.showCommentsUI :

 

Adding Guest Login

Adding guest login is simple: Check the "Allow guest comments" checkbox and click the "Save changes" button at the bottom of the page. Refresh your comments page and see the additional "Guest Login" in the login bar:

If you set the "Allow guest comments" radio button to "Yes", you will also see the "As Guest" option in the Login add-on :

 

You can also decide whether an email address is required for guest users, and if to request a required nickname from the guest:

If all three checkboxes are checked then when a user clicks the "Guest" button he is prompted to insert a nickname and an email address:

If an email is not required, or the guest nickname is not requested, the add-on will not display the relevant textbox. 

Adding Site Login

Adding site login is a bit more complex:

Set the useSiteLogin parameter of the comments .showCommentsUI method to true: 

var params =  { 
    categoryID: 7623701,
    streamID: '',
    version: 2,
    containerID: 'commentsDiv',
    useSiteLogin: true,
    cid:''
}

You will now see the site login button instead of the Gigya Login button. When you set the comment with useSiteLogin=true , clicking the Post button will be the same as clicking the Login button except the comment won't be automatically posted. 

If you want the comment automatically posted after the site Login event, add a callback function to the event object of onSiteLoginClicked.  This will be called when the user finishes logging-in. For example:

// onSiteLoginClicked event handler
function onSiteLoginClicked(event) {
    // set GAC from server side
   event.callback();
}

Clicking the site login button at the bottom of the page fires an onSiteLoginClicked event. To register to this event, set the onSiteLoginClicked parameter of the comments .showCommentsUI method with a reference to an event handler function. This function should open a popup or redirect the user for the site login page. The following sample code illustrates this:

// onSiteLoginHandler event handler
function onSiteLoginHandler(event) {

    // Site Login button clicked
    // open a popup or redirect the user for the site login page}

var params =  { 
    categoryID: 7623701,
    streamID: '',
    version: 2,
    containerID: 'commentsDiv',
    useSiteLogin: true,
    onSiteLoginClicked: onSiteLoginHandler,   // registering to the onSiteLoginClicked event
    cid:''
}

gigya.comments.showCommentsUI(params);  

Note that the popup or site login page should include Gigya's Login add-on.  

Note: If you have a site login implementation that redirects the user or refreshes the page after logging in, then logging the user into the site from the Comments add-on leads to the user losing the comment they have typed. We recommend combining the Comments add-on with an AJAX-based login process that does not require a redirect or page refresh.

Social Network Publishing

  • The Share to social network check box is checked by default, meaning that the Share check boxes for the post are pre-checked and comments submitted by the users will be automatically shared to the selected social network or networks if they do not un-check the boxes.
    If you change Share to social network check box to unchecked, the Share check boxes for the post are not pre-checked and users will be able to submit comments, but the comments will not be automatically shared to social networks unless they check the corresponding boxes for the post.
  • Checking the Enable direct comment linking checkbox causes shared comments to link directly to the specific comment on the page, rather than simply linking to the page that contains the comment.

Layout Customization

This section allows you to change a few aspects of the Comments 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 above the  comments stream, at the top of the add-on. You may change this by checking the 'Bottom' radio button. As a result the canvas will appear below the comments stream, at the bottom of the add-on.

Show Newly Added Comments

This section allows you to specify whether the add-on should be refreshed in real-time and show newly added comments that were posted after the user has entered the page where the add-on is displayed.
T his drop-down menu allows you to select one of the following three options:

  • Off - when selected, do not show notifications for new comments. This is the default option. This means that the comments add-on will not show the new comments that were posted after entering the page where the add-on is displayed.
  • Show only new comments count - when selected, display the number of new comments. When this option is selected, the Comments add-on will display the counter of the new comments and a link. The user will be able to click the "Click to show" link in order to display the new comments.
  • Automatically show new comments - when selected, all new comments will be displayed automatically.
 

 

Note: No matter what setting is selected for the "Show Newly Added Comments", there is no impact on the page performance.

When the setting is "Automatically show new comments", you can pause the comments stream by clicking "Pause live stream":

Click the "Resume live stream" link to continue the comment stream.

Displaying Number of Comments

The checkbox allows you to display or hide the number of comments in the stream.

You can choose whether to display an RSS button and a Subscribe button. This allows users to subscribe to comments streams by email. Read more in the Subscribing to Comments section.

Other Settings

This section allows you to change the default settings of:

  • Comment sorting, including different sorting options and allowing user sorting. 
  • Comments threading
  • Allowing users to edit their own comments
  • Allowing users to delete their own comments
  • Enabling embedding of media
  • Enabling use of links within comments
  • Enabling Google Analytics Social Data Hub integration
  • Enabling in-line tagging of commenters
  • Enabling rich text formatting
  • Enabling voting on comments, including allowing negative voting and showing separate counter for negative voting
  • Maximum comment length
  • Replies default view
  • Allowing logged-in users to post an anonymous comment or review

 

Comments Threading

By default comments threading is enabled, so commenters can reply to other comments, and the replies are displayed in a nested manner. If you prefer not to allow comments threading, select 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 5.

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.

Maximum Comment Length

You may select the maximum length of the comments. If you do not set this value, the default maximum length of the comments is 5000 characters.

In-line Tagging of Commenters

You can allow commenters to tag other commenters from the comment stream. 

When this option is checked, you can easily enter the commenter you want tagged, either by:

  • Clicking the "tag commenter button". When you click the icon, the commenters in this stream will be displayed and you may choose one or more to add to the comment (up to 15):

 

  • Or by entering a "@" symbol in the text box, in which case, the add-on will display an auto-completion drop-down list that contains the list of commenters.  When you continues to enter (or change) text, the drop-down will be filtered by the entered text, and you can select the commenter.

     

Once you tag a commenter (or commenters), you may post the comment:

The tagged commenter will receive a notification email regarding the tagging if he selected "Follow replies to my comments". 

In mobile versions the tag in the comments is supported, though at this time tagging commenters is not yet supported.

 

Enable Links in Comments

If this checkbox is checked, URLs that have been entered as part of a comment are displayed as clickable links in the published comment. The links are configured with the "nofollow" option and open in a new window. For the purpose of this feature, URLs are strings that begin with "http://", "https://" or "www.".

For example, in a comment such as this one:

If you enable links in comments, your website users will be able to click "http://www.example.com" to open the link in a new window. If you disable links in comments, URLs will appear as regular text.

By default, this option is not enabled.

Allow Users to Edit their own Comments

Check the 'Allow users to edit their comments' checkbox to enable the editing feature.

Updated comments are treated as new comments in the following sense:

  • Edited comments will go through blocked words and spam filters again and may be rejected.
  • When comments are pre-moderated, an edited comment will move to 'pending' state and will not appear in the thread until approved.
  • If a comment was flagged and cleared by a moderator, it can be flagged again once edited.
  • Blocked users, or users accessing from a blocked IP will not be able to edit.
  • Editing a Highlighted comment will remove the comment's highlight.

Edited comments are treated differently than new comments in the following sense:

  • Guest users cannot edit.
  • Editing a flagged comment will not remove the flag.
  • A comment that was posted by an identified user cannot be edited to be posted anonymously. 
  • Edited comments are not counted as additional comments.
  • Edits are not updated live (i.e other users will only be able to see the edited comment on the next page reload).

When a category is defined as 'Read only', editing is disabled.

Allow Users to Delete their own Comments

When you check the checkbox, a "Delete" button appears, allowing a logged-in users to delete their own comments:

Enabling Voting on Comments

The "Enable voting on comments" checkbox determines whether to make voting on comments available for users. 

  • "Allow negative voting" determines whether users will be able to vote negatively (thumbs down) on comments. If these two check-boxes are checked, the Comments add-on shows a set voting icons next to each comment. If negative voting is not permitted (default configuration), a "like" button is displayed in addition to the regular thumbs up button.
  • "Show separate counter for negative voting" determines whether to place a separate counter for negative votes (thumbs down) on comments.  If these two check-boxes are checked, the Comments add-on shows a set voting icons next to each comment, with separate counters.

Like Button

In addition to the regular thumbs up button, a Like button appears:

Once the Like button is pressed, the thumbs up icon turns to green, and the "Like" turns to "Unlike". When the "Unlike" is pressed, the thumbs up icon changes back to gray, and the "Unlike" changes to "Like".

To disable this feature, set  streamSettings. allowNegativeVoting to "true", u sing  comments.setCategoryInfo. The outcome will be that the thumbs up and thums down will appear, and the Like button won't.

Sorting Comments

The comments can be displayed in different orders.

If the "Enabling voting on comments " checkbox is not checked, you may sort the comments according to one of the following orders:

  • Most recent on top (default) - the comments are sorted by the timestamp of the post. The first comment is the latest one (most recent).
  • Most recent on bottom - the comments are sorted by the timestamp of the post. The first comment is the oldest one (least recent).
  • Most relevant on top -  the thread with the most recent reply is displayed first.

If the "Enabling voting on comments" checkbox is checked, you have two additional sorting options:

  • Most voted on top - the comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread. The first comment is the one that has the highest votes.
  • Most voted on bottom - the comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread. The first comment is the one that has the lowest votes.

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. Once a new sort is selected by the user, the comments are reloaded according to the new sort. 

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.

Enable Embedding Media Items

The add-on enables you to embed media items of supported providers to your comments.

When you check the "Enable embedding media" checkbox, you will see the "attach" icon:

 

 

Note: In order attach a media item, the user must be logged in (they may be logged in as a guest user).

 

When clicking on the "attach" icon, the add-on will open an "add media item" dialog:

Enter the URL of the embedded media item you wish to add to the comment.

You can embed:

  • An image
  • Audio
  • A video

For example, the following image shows an embedded video item from Vimeo:

The supported vendors are:  Youtube, Vimeo, Flicker, CNN, Facebook, Pinterest, Twitter, SoundCloud, Instagram, Imgur, Twitter Pics, Tumblr, Spotify, rdio, last.fm, Pandora, SmugMug, PhotoBucket, Ustream, CollegeHumor, FunnyOrDieThe Onion, Dropbox and Brightcove.

Anonymous Posts 

The add-on enables you to allow logged-in users to post an anonymous comment or review.

When you check the "Allowed anonymous post by logged-in users" checkbox, the add-on displays a checkbox that when checked, it enables the user to post anonymously:

If non-logged-in users want to post anonymously, they can post as guests.

Notifications

This section allows you to register a callback URL which will be sent notifications when a new comment event is triggered or when a comment status change event is triggered. Comment statuses can be "published", "pending" or "rejected" (see the comment object).

Notifications are sent as an HTTP/HTTPS post. For details of their content, see Comment Notifications

Notifications can also be generated using the comments.setCategoryInfo API.

Site Restrictions

Gigya offers you the option to manage a custom black list of words and phrases to be filtered in comments, and to block IP addresses. You can read more in the Site Restrictions section, or go directly to the Site Restrictions on Gigya's site.

Commenting Rate Limit

Gigya supports rate limits on commenting in order to prevent spamming and abuse. This includes limiting the number of root comments and replies a user may post per stream in a day, and limiting the number of root comments and replies a user may post per site in a day.

Importing Commenting Systems

Gigya supports importing third-party commenting systems. If you wish to migrate to Gigya's commenting system, you can import your existing comments to Gigya and display them on your site. For this operation, please contact Gigya Support via the link in the top-right of your Gigya Dashboard

Comment Stream Subscriptions and Notifications

Notification of Comments Replies

By clicking the "Follow replies to my comments", logged-in users can choose to receive notifications when other users reply to their comments. After clicking, the user is notified by email whenever anyone replies to their comments (this feature is not available to anonymous commenters).
 

Subscribing to Comments

You can allow all your users whether they are logged-in or not to subscribe to a comments stream by email. First, make sure that in the  Comments Settings  page, the Display Subscribe Links radio button is set to Display. This causes the comments add-on to display the "Subscribe" and "RSS" links under the comment box:

When a user clicks the RSS button in a supporting browser, an RSS reader opens , showing the RSS feed for this comments stream. If their browser does not support RSS, clicking the link opens the XML file.

When a user clicks the Subscribe button, the following dialog box opens:

If the user is logged in, their email address is pre-filled in the dialog box, and they can change it if they wish.

Otherwise, the user has to enter a valid email address.

After the user clicks "Subscribe", the Gigya system begins sending them email notifications about updates to the current stream. Notifications are not immediate: Gigya checks for updates in the comment stream every few hours, and sends the user an email saying that comments have been added to the stream to which they have subscribed.

Once an email address has been entered, the Subscribe button changes to Unsubscribe so that the user can choose to stop receiving notifications. The user can also use the "Unsubscribe" link included in the update email for the same purpose.

Note:

  1. Notification emails are not sent for comments which the subscriber has already viewed by visiting the comments page. Gigya only sends notifications for newly posted comments which the subscribed user has not seen.
  2. Only one batch notification email is sent at a time, regardless of how many new comments have been posted.

Comment Email Templates

Users who subscribe to comment streams receive a Stream Subscription Email notifying them that they have subscribed to the stream and a Comments Reply Email notifying them when someone replies to their comment.
The default form of these emails exists in all supported languages. The language of the comment stream determines which language will be used in the email. Comment email subscriptions and the languages they use can be set in comments.subscribe and comments.setUserOptions.

The default content of the notification emails can be customized by site administrators using the Comments Email Templates (Settings >> Comments >> Email Templates in the Gigya Console).
When customized templates are created, they are for a specific Comment Category and language. 

Default Stream Subscription Email

Default Comment Reply Email

Content of Email Templates

Customized email templates define email content (from, subject and body) for a specific language and comment category. The email template is an HTML template that supports placeholders and META tags.

  1. META tags define the header of the email.
  2. Placeholders are variables that Gigya replaces in the email body (text) with actual values when the email is sent. All email templates must contain an %unsubscribeLink% placeholder. 
     

Note: Email templates cannot be saved without an unsubscribe link (%unsubscribeLink%).

 

The supported META tags:

  • <META name="from"  content="Name <notifications@gigya-comments.com>" /> - specifies the source of the email, i.e., what will be written in the "from" of the email.
  • <META name="subject" content="Account Activation" /> - defines the subject of the email.

The supported placeholders for Stream Subscription Emails:

  • %unsubscribeLink% - Required.
  • %streamTitle% - Title of the comment stream, taken from the Stream object.
  • %streamURL% - URL of the comment stream, taken from the Stream object.
  • %commentTitle- The title of the review posted (reviews may include titles while comments do not). In case the email contains several comments, %commentTitle% will hold the title of the most recent comment.

The supported placeholders for Comments Reply Emails:

  • %unsubscribeLink% - Required .
  • %streamTitle% - Title of the comment stream, taken from the Stream object.
  • %streamURL% - URL of the comment stream, taken from the Stream object.
  • %senderName% - Name of the person who posted the comment, taken from the Sender object in the Comment object.
  • %comment% - Text of the comment, taken from the commentText field in the Comment object.
  • %commentStart% - First seven words of the comment, up to a limit of 50 characters.
  • %senderPhoto% - Picture of the person who posted the comment, taken from p hotoURL in the Sender object in the Comment object.
  • %threadCommentTitle- The title of the root comment which was replied to (relevant only for reviews).
 

Creating Customized Emails

The Email Templates page has two tabs, one for the Stream Subscription Email and one for the Comments Reply Email

 

 

  • To customize the email for a particular language:
  1. Select either the Comments Reply Email tab or the Stream Subscription Email tab.
  2. Enter a comments category at the top of the page.
  3. Click the "Add Template" button.
  4. Select the language.
  5. Edit the content of the template
  6. When you finish click the "Save Settings" button. 
  •  To preview the email press the preview button  in the Settings column.
  • The language used for the email is set by the language of the comment stream.

UI Customizations

We provide several levels of customization for the Comments 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.

Template Classes

The  templates  parameter in comments.showCommentsUI defines a series of classes each of which represents a single user interface element in the Comments add-on. Each template is a layout definition for a group of related graphics elements in the Comments add-on and each template is sub-divided into a series of classes each of which represents an individual graphical element within that template.

Use this parameter to override the default design of the Comments add-on, to change the location of elements, prevent them from being displayed and to apply CSS to them.  The templates are: 

Comments Plugin (commentsPlugin)

Can be used to set the order in which each of the following template elements appear and whether it appears at all. Most of the commentsPlugin classes refers to one of the other templates; for example gig-comments-comments controls the comment template.

  • gig-comments-comments
  • gig-comments-composebox
  • gig-comments-header
  • gig-comments-more
  • gig-comments-updates

Header (header)

Can be used to set the order in which each class appears, whether it is displayed and to apply CSS styling.

  • gig-comments-count
  • gig-comments-header-left
  • gig-comments-rss
  • gig-comments-sort
  • gig-comments-subscribe

Updates (updates)

Can be used to control the order in which each class appears, whether it is displayed and to apply CSS styling.

  • gig-comments-updates-link
  • gig-comments-updates-text

Comment (comment)

Can be used to control the order in which each class appears, whether it is displayed and to apply CSS styling.

  • gig-comment-body
  • gig-comment-deleteLink
  • gig-comment-editbox
  • gig-comment-edited
  • gig-comment-editLink
  • gig-comment-flag
  • gig-comment-mediaItem
  • gig-comment-photo
  • gig-comment-replies
  • gig-comment-repliesArrow
  • gig-comment-repliesArrow-text
  • gig-comment-replybox
  • gig-comment-replyLink
  • gig-comment-shareLink
  • gig-comment-status
  • gig-comment-time
  • gig-comment-title
  • gig-comment-username
  • gig-comment-viaProvider
  • gig-comment-vote-total
  • gig-comment-vote-pos
  • gig-comment-vote-neg
  • gig-comment-userBadges
  • gig-comment-commentBadges

Compose Box (composebox)

Can be used to control the order in which each class appears, whether it is displayed and to apply CSS styling.

  • gig-composebox-cancel
  • gig-composebox-close
  • gig-composebox-cancel
  • gig-composebox-editor
  • gig-composebox-follow
  • gig-composebox-guest-login
  • gig-composebox-logout
  • gig-composebox-media-preview
  • gig-composebox-photo
  • gig-composebox-post
  • gig-composebox-ratings
  • gig-composebox-share-providers
  • gig-composebox-site-login
  • gig-composebox-social-login
  • gig-composebox-summary-input
  • gig-composebox-title
  • gig-composebox-userBadges

My Review (myReview)

Can be used to control the order in which each class appears, whether it is displayed and to apply CSS styling.

  • gig-selfreview-body
  • gig-selfreview-body-container
  • gig-selfreview-nameAndLogout
  • gig-selfreview-ratings
  • gig-selfreview-summary
  • gig-selfreview-summary-container

Running Example

In the following example the Comments add-on is presented, with graphic elements laid out differently than the default.  The "Show more comments" link has been moved to the top and the header placed above the compose box.  Some of the classes in the header are not displayed.

 

 

Example Code

<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">
    // Optional - define templates to changes structures in the Comments add-on
    var templates = {
        commentsPlugin: '<span style="color:blue;">This is the more option(usually appears at the bottom):</span><span class=gig-comments-more></span><br><br><br>' +
                        '<span style="color:blue;">This is the header: </span><span class=gig-comments-header style="float:right"></span><br><br><br>' +
                        '<span style="color:blue;">This is the compose box:</span><span class=gig-comments-composebox> </span><br>' +
                        '<span style="color:blue;">This is the list of comments:</span><span class=gig-comments-comments> </span>', 
 
         header:        '<span style="color:red;">header count:</span> <span class=gig-comments-count></span><br><br>' +
                        '<span style="color:red;">header subscribe:</span><span class=gig-comments-subscribe> </span><br>',

        comment: '<span style="color:green;">This is the username:</span> <span class=gig-comment-username style="color:blue;"></span><br>' +
                 '<br><br><span style="color:green;">This is the Photo: </span><span class=gig-comment-photo style="float:right;"></span><br>' +
                 '<span style="color:green;">This is the Date String:</span> <span class=gig-comment-time style="color:blue;"></span><br>' +
                 '<span style="color:green;">This is the Comment Body:</span> <span class=gig-comment-body style="color:blue;"></span><br>' +
	 	         '<span style="color:green;">This is the Replies Count:</span> <span class=gig-comment-count style="color:blue;"></span><br>' +
                 '<span style="color:green;">This is the Reply Button: </span><span class=gig-comment-replyLink style="color:blue;"></span><br><br>' +
                 '<span style="color:green;">This is the Flagging option:</span> <span class=gig-comment-flag style="color:blue;"></span><br>' +
                 '<span style="color:green;">This is the comment vote total:</span> <span class="gig-comment-vote-total"></span><br>' +
                 '<span style="color:green;">This is the Voting option:</span> <span class=gig-comment-vote-pos style="color:blue;"></span>' +
                 '<span class=gig-comment-vote-neg style="color:blue;"></span><br>' +
                 '<span style="color:green;">This is the comment reply box:</span> <span class=gig-comment-replybox ></span><br>'
    };
    var params =
    {
        // Required parameters:
        categoryID: 7623701,
        containerID: 'commentsDiv',
		streamID: 'foo6', 
		version: 2,
        // Optional parameters:
        templates: templates,
        cid: ''
    };
    // Load the Comments add-on
    gigya.comments.showCommentsUI(params);
</script>
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API Key.
  • If you are using https, be sure to further adjust the JS API url to: https://cdns.gigya.com/js/gigya.js?apikey=<Your_API_Key>.

HTML Elements Style (CSS)

Any elements on the add-on that has an ID can be overridden with supported style attributes. There are dozens of elements on the add-on. identify the HTML elements on the add-on using developer tools, 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-button-post-text {color:Yellow;background-color:black} </style>

Sharing Comments to Social Networks

Users can share their comments to social networks by clicking the "Share" link under the comment to be shared:

Once the "Share" link is clicked, a mini Share add-on will pop up to suggest to the user to share his comment to the social networks. The user is given an option to choose to which social network he wants to post the content. When the user presses the social network's button, Gigya will publish the user's reaction to the selected social network.

In order for this share to work, follow these two easy steps: 

  • Step 1 - Construct a UserAction object called shareUserAction , which represents the action taken by a user on your site. The newsfeed that is published to the social networks is constructed from the fields of this object. All the fields of this object are optional. 
  • Step 2 - include the newly constructed shareUserAction object in the comments.showCommentsUI parameter

Step 1: Construct a UserAction Object 

The UserAction object represents a user action. We use the UserAction object constructor for this purpose:

var shareUserAction = new gigya.socialize.UserAction();  

 

By default, the shareUserAction object fields are mapped as follows: 

  • description - the description field receives the comment text.
  • title - the title field receives the following text: "%userName commented on %pageTitle", when %userName and %pageTitle are placeholders.
  • linkBack - the linkBack field receives the URL of the page where the commenting stream is located.

After you have constructed the object, you can use the various UserAction member methods to set the rest of the object's properties, or change existing ones. For example:

shareUserAction.setSubtitle("This is my sub title");
...

 

The UserAction's object properties represent the various items of which a User Action may consist: Title, etc.

Step 2: Include the shareUserAction in the Comments add-on parameters

var params =  {
    categoryID: 7623701,
    streamID: '',
    containerID: 'commentsDiv',
    version:2, 
    userAction: shareUserAction  }; // The UserAction object from Step 1

Comments UI in Mobile View

When the comments .showCommentsUI deviceType parameter is set to mobile, the comments UI is displayed in the mobile mode. Also if deviceType is set to auto and you open the page on mobile, it will also display the mobile layout:

 

In this mobile mode some of the Comments UI functionality is not supported:

  • Flagging comments
  • Compose box side bar will be hidden, so no rich text, user tagging, media items
  • User won't be able to collapse or uncollapse the thread (hide the element)
  • Users will see the tagged user in the comments, though at this time tagging commenters is not yet supported.

When an embedded media item is in the comments stream, clicking on the HTML media item will redirect the browser to the URL.

Comments Counter in Share Bar

Gigya's Share Bar add-on is built out of one or more buttons, arranged horizontally in a bar. You can add a Comments button to your Share Bar, with a counter indicating the number of comments made in that specific comments stream. The comments stream is identified by its unique categoryID and streamID. To learn how to embed a Share Bar with Comments button, read the Adding a Comments Counter section of the Share Bar add-on.

Browsers Compatibility

Comments version 2 is supported from the following browser versions:

  • Chrome: from version 26
  • Firefox: from version 22
  • IE : from version 9
  • Safari: from version 6

For older browsers the system will automatically fall back to comments version 1.

Mobile Compatibility

Comments version 2 is supported from the following OS versions:

  • iOS: from version 6
  • Android: from version 4.x
  • Windows mobile: from version 8.x

Comments version 2 is supported from the following browser versions:

  • Chrome: from version 4.x
  • IE : from version 10
  • Safari: from version 7.0.4

For older browsers the system will automatically fall back to comments version 1.

Right-to-Left Localization

Gigya provides right-to-left language support for the Comments add-onThe add-on will be displayed according to the locale:

 

Responsive Design

The Comments add-on is designed to respond fluidly as the size of the browser window is changed. The mode can be set to Mobile or autoDetect where applicable. Read more in the Mobile View section.

Support for Custom Texts

The Comments add-on has a long list of keys that represent texts in the add-on, for example, "thank_you_for_subscribing" represents the text "thank you for subscribing". 

You can override these existing texts, and use your own custom texts in the comments add-on. This is done with the customLang  parameter in comments.showCommentsUI, by setting pairs that include the key that represents a text element in the UI, with the text to which you want to change:

customLang = {textKey1text1,textKey2text2,[...]}.

For example:

 

params.customLang = {
            num_comments: '%num talkbacks',
            write_a_comment: 'Write a talkback'
        };

For the full list of existing keys, see our customLang documentation.

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, 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:

  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. Customers using this code should note that customizing pages for search bots can be a violation of search engine guidelines; for more information see https://support.google.com/webmasters/answer/66355.
  2. Inject HTML Comments data: If a search engine is identified, fetch the raw comments HTML by setting the dataFormat parameter of comments.getComments to'html':
  3. Print this HTML inside of the comments DIV container. 


Additional Information

 

Sending RaaS Email From Your Domain

There are cases when you may need to send your users emails via your own domain name instead of from the Gigya Server. If that is the case the first thing you need to do is notify Gigya by contacting Support via the Support tab in the Gigya Console.

The steps you then need to perform are as follows:

  • Provide Gigya with the IP or IP's of your email server or servers.
  • Provide Gigya with the server credentials (i.e., username and password).
  • Provide Gigya with at least one email From address.
    • This needs to match the email address(es) that you will configure in the email template headers of the Gigya Console. It can be a valid address, e.g., support@yourdomain.com or an invalid address, e.g., no-reply@yourdomain.com, however, it must match what you configure in the console (so the emails are routed correctly).
  • Let Gigya know if your server(s) use a port other than 25 for SMTP.

Gigya will then provide you with information to complete the setup process:

  • You will receive an IP or list of IP's to add to your email servers SPF and/or DKIM file.
  • You will then need to add these IP's to your domains white-list.

Changes To Email Templates

Be sure to update the header information in any email templates you have created to reflect the changes (if necessary). If you are using Gigya defined placeholders, these will update automatically.

It is important to note that server based changes such as these are global for the account (domain/DNS record) and can not be restricted to any single API key.