Ratings and Reviews

Skip to end of metadata
Go to start of metadata

Overview

A migration to the Gigya platform is performed by exporting data from your current system to a JSON file and sending it to Gigya to import. This guide will help you develop an export schema that will seamlessly import into our platform.

The native Gigya Ratings and Reviews import file format is a JSON file containing information for each category, stream, author, and comment (we will refer to a rating/review as a “comment” in this guide). The information included about authors depends largely on whether the comments will be imported with associated users in the Gigya database or as guest comments.

In addition to our native JSON format, Gigya supports a number of export formats from other commercial vendors. Please check with your Implementation Consultant to determine whether the vendor from which you are migrating is supported out of the box.

JSON Structure

In most cases, you may only have a single category. Categories are used primarily to distinguish between distinct settings for different streams or limit the scope of moderation for different moderators. If all of your streams will use the same settings and moderators, there is no reason to break them up into separate categories.

The settings object must be at the top of the file. It should be followed by categoriesstreamsuserscomments, and votes (specifically in that order, though users may alternatively be listed before categories).

Parameters with empty values for any given object may be omitted. Separate each object (e.g. comment) by a line break. Lines breaks are not necessary between individual parameters within an object.

There is no limit to the file size, so all of your data can be in a single file.

Ratings Range

Gigya supports only integer ratings from 1 to 5. Half ratings and zero ratings will be ignored. If a comment does not have either a valid rating or a non-empty value for commentText, it will be rejected.

Tying Comments to Users

In most cases, if the comment authors are users who registered on your site, you will want to tie their comments to their login identity. If the users already exist in the Gigya database or are being imported in a separate task, you only need to include the UID of the user as it exists in Gigya. For any use you have not already imported, you should include either firstName and lastName or a nickname so that it will be displayed as the person who commented. Otherwise the commentor will be displayed as “anonymous”. Including email will allow you to link users logging in socially with their existing UID.

Guest Comments

In the case where you do not have users records in the system to represent the comment authors, you can import them as guest comments. In this case, you must set guestName and guestEmail. You can also choose to set profileURL and photoURL, which will be used in the display of the comment.

Caveats

Replies to reviews cannot contain ratings or commentTitle, but must contain commentText. Whether commentTitle or commentText are shown and required on the initial review, is determined by the category settings available in the Gigya Dashboard.

Combining Comments and Ratings & Reviews

All Comments and Ratings & Reviews data for a single site should be included in a single file that can be imported in a single run. Please see the Gigya Comments Import Guide for more information on the data structures and fields for non-R&R comments.

Object Fields

Please note that ALL parameters are CASE SENSITIVE, just like the Gigya API.

Settings

 

RequiredField NameTypeDescription
apiKeystringThe apiKey into which the content is to be imported.
importFormatstringThe format of the file you are providing. This should be gigya-comments-combined-json.
totalCategoriesintegerThe number of categories included in the file.
totalStreamsintegerThe number of streams included in the file.
totalUsersintegerThe number of new users to import in the file.
totalCommentsintegerThe number of comments included in the file.
totalVotesintegerThe number of votes included in the file.

 

Categories

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category. Streams and comments within this category must contain a categoryID exactly matching an ID listed in the categories array.
operationModestringThe operation mode determines whether the category contains Comments or Ratings & Reviews.

 

Streams

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category to which the stream of discussion belongs.
streamIDstringThe unique ID of the stream to which you would like to set information. Note: the string is limited to 150 characters and is case-sensitive.
streamTitlestringThe title assigned to the commenting stream. This title you assign here will be assigned to each comment posted to be used for RSS & HTML outputs.
streamURLstringThe stream URL assigned to the commenting stream (usually the URL of the page where the commenting stream is presented). This URL you assign will be assigned to each comment posted to be used for RSS & HTML outputs. This URL will link back from the RSS or HTML page to the original post where the comment was added.
Note: Gigya will verify that the streamURL belongs to your site (as configured for your API key in the Dashboard section on Gigya's website).
createDateintegerThe date the stream was created as a unix timestamp in milliseconds.
streamTagsstring or arrayEither a comma-separated list or an array of tags (strings) that should be associated with the stream. The tags you assign here will be assigned to each comment posted to be used for RSS and HTML outputs.
moderationModestringThe values accepted for the moderation mode are:
  • inherit - the stream will use the category moderation mode settings (this is the default if not set)
  • pre - all comments will be pending moderator approval
  • post - all comments will be approved automatically (per spamming & other auto moderation rules)
  • guest - all comments submitted by guests will remain hidden until moderation
readOnlybooleanDetermines whether the stream is read only or not. The default value is 'false', meaning not read only.
disabledbooleanDetermines whether the stream is disabled or enabled. The default value is 'false', meaning enabled.

 

Users

 

RequiredField NameTypeDescription
UIDstringThe unique ID of a logged-in user, with which this method call is associated. See User.UID for more information. If the user is not a guest (guestName parameter is not defined) this field is Required

Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Login with account linking (best practice), please refer to the Login Implementation guide.

firstNamestringThe first name of the user who commented. This field is only necessary when the user does not already exist in the Gigya database, and you are not including nickname.
lastNamestringThe last name of the user who commented. This field is only necessary when the user does not already exist in the Gigya database, and you are not including nickname.
nicknamestringThe display name of the user who commented. This is shown as the commenter's name in place of firstName and lastName. This field is only necessary when the user does not already exist in the Gigya database, and you are not including firstName and lastName.
emailstringThe email of the user who commented. This field is only necessary when the user does not already exist in the Gigya database. If that is the case, it is necessary for account linking if the user subsequently logs in socially.
photoURLstringThe photo of the commenter.
profileURLstringThe profile URL of the commenter.

 

Comments

 

RequiredField NameTypeDescription
categoryIDstringThe identifier of the comments category to which the stream of discussion belongs.
streamIDstringThe unique ID of the stream to which you would like to set information. Note: the string is limited to 150 characters and is case-sensitive.
IDstringThe unique identifier for the comment.
commentTextstringThe message body of a comment. The text may be maximum 5,000 characters long.
* This parameter is Required given the following conditions:
  • If you are posting to a categoryID that is defined with 'Operation mode: Rating & Reviews'.
  • And, in the Comments Settings of the relevant categoryID, 'Enable Comment Body:' is set to 'Show' and ‘Required.
  • Or, the parentID parameter is specified (i.e. you are posting a comment to a review).

In any other case the commentText is irrelevant and is ignored.

commentTitlestringA title for the comment. The title may be maximum 250 characters long.
* This parameter is Required given the following conditions:
  • If you are posting to a categoryID that is defined with 'Operation mode: Rating & Reviews'.
  • And, in the Comments Settings of the relevant categoryID, 'Enable Comment Titles:' is set to 'Enable'.
  • And, the parentID parameter is not specified (i.e. you are posting a Review and not a comment to a review).

In any other case the commentTitle is irrelevant and is ignored.

ratingsJSON objectAn object that defines user ratings for this stream. The object structure is: {"_overall": ratingValue, "dim1ID": dim1RatingValue}, where the ratingValue and dim1RatingValue are integers between 1-5, and dim1 is the ID of a ratings dimension defined in the category settings.
* This parameter is Required given the following conditions:
  • If you are posting to a categoryID that is defined with 'Operation mode: Rating & Reviews'.
  • And, in the Comments Settings of the relevant categoryID, 'Enable Ratings:' is set to 'Enable'.
  • And, the parentID parameter is not specified (i.e. you are posting a Review and not a comment to a review).

In any other case the ratings is irrelevant and is ignored.
Note: Rating a stream is permitted only for a logged in user, which hasn't rated this stream before (each user may rate each stream only once). This method will return an error to a forbidden rating attempt.

UIDstringThe unique ID of a logged-in user, with which this method call is associated. See User.UID for more information. If the user is not a guest (guestName parameter is not defined) this field is Required

Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Login with account linking (best practice), please refer to the Login Implementation guide.

guestNamestringGuest user name. This field is relevant if the user who posted this comment is a guest user, in which case this field is Required.
guestEmailstringGuest user email. This field is relevant if the user who posted this comment is a guest user, in which case this field is Required.
parentIDstringThe identifier of the parent comment. In case this comment is a reply to another comment, this field is the ID of the comment to which this comment replies.
cidstringA string of maximum 100 characters length. This string is associated with each transaction and will later appear on reports generated by Gigya in the "Context ID" combo box. The cid allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. The "Context ID" combo box lets you filter the report data by site/application context.
tagsarrayThis parameter is a strings array representing a list of tags, e.g.: ["tag_a","tag_b"]. Each tag in the array is assigned to the posted comment. Tags can be used to filter comments when calling comments.getComments, to get only comments that match the tag.
statestringThe state of the comments for import. The optional values for this parameter are: 'approved' (default), 'pending', or 'rejected'.
createDateintegerThe date the comment was created as a unix timestamp in milliseconds.
ipstringThe IP address from which the comment was posted.
photoURLstringThe photo of the commenter.
profileURLstringThe profile URL of the commenter.

 

JSON Samples

The sample provided below  represents a variety of possible combinations of fields depending on the structure of your existing data. Please see above to identify which fields are required and which are optional. Your existing data may only represent a subset of the fields shown in the samples so long as the required fields are present. We encourage you to reach out to your Implementation Consultant for more information and to review.

Flat JSON

 

{
	"settings": {
		"apiKey": "<YOUR-­API-­KEY>",
        "importFormat": "gigya-­comments-­combined-json",
        "totalCategories": 1,
        "totalStreams": 2,
        "totalUsers": 1,
        "totalComments": 3 },
    "categories": [ {
        "categoryID": "Restaurants",
        "operationMode": "Ratings & Reviews" } ],
    "streams": [ {
        "streamID": "849273",
        "categoryID": "Restaurants",
        "streamTitle": "Siam Thai",
        "streamURL": "http://mysite.com/reviews/siam-­thai.html",
        "streamTags": ["thai","asian"],
        "moderationMode": "inherit",
        "status": "enabled",
        "createDate": 1297087491153 },
        {
        "streamID": "820742",
        "categoryID": "Restaurants",
        "streamTitle": "Corner Grill",
        "streamURL": "http://mysite.com/reviews/corner-­grill.html" } ],
    "users": [ {
        "UID": "127472534",
        "firstName": "Jason",
        "lastName": "Smith",
        "email": "jason.smith@commentor.com"  } ],
    "comments": [ {
        "ID": "7812397",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "UID": "127477523",
        "ratings": {"_overall": 4, "food": 5, "atmosphere": 3},
        "commentTitle": "Great place!",
        "commentText": "This was sooo yummy!",
        "cid": "website",
        "state": "approved",
        "tags": ["mytags","rating"],
        "createDate": 1297087491153 },
        {
        "ID": "7812399",
        "parentID": "7812397",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "guestName": "Suzzie Song",
        "guestEmail": "suzzie@acme.com",
        "photoURL": "http://cdn.socialnetwork.com/avatars/1234567",
        "commentText": "I totally agree!",
        "state": "approved",
        "createDate": 1297087491153 },
        {
        "ID": "7812582",
        "streamID": "849273",
        "categoryID": "Restaurants",
        "UID": "127472534",
        "ratings": {"_overall": 4},
        "commentTitle": "Not bad.",
        "commentText": "It was pretty good and had great service",
        "state": "approved",
        "createDate": 1297087491153 } ]
}