UGC Feedback API

Follow

The User Generated Content Feedback API provides the ability to store "flag" based data that you may need from your users. Some examples would be Likes, Votes, Ratings, Approval/Disapproval, etc. The API is built to be lightweight and fast to add and retrieve data on the fly. It is also built in a generic way so that you can "Flag" any content you may want to track in any custom scenario.

This API is implemented within the REST, WCF and OData API's

Methods

SaveBooleanFeedback(BooleanFeedback feedback)
This method is used to save True/False data into the Feedback API and takes a BooleanFeedback Object. Because most data in the Feedback API can be considered “True” or “False” this is the most commonly used method. This method can be used to store “Like”, “Vote”, “Approve/Dissapprove”, “Comment” and “Counter” data. Each of the previously mentioned “Submission Types” has either positive (true) or negative (false) requirements that are handled by the API.

SaveRatingFeedback(RatingFeedback feedback)
This method is used to save rating related data into the feedback API and takes a RatingFeedback Object. An example use for the rating feedback type would be “Star Ratings” with a range of 1-5 stars. There is no limit as to how high a rating value can be set to (so we can easily support 1-10 stars if required).

GetFeedbackAggregate(FeedbackSearchArgs searchArg)
This method is used to perform custom searches on your user feedback data and return an aggregate of the results from your search criteria. Please see the Object Definition Section where we describe the FeedbackSearchArg Object in full. This call works on both Boolean and Rating based feedback and will return Counts (Number of Likes), Sums (Total Rating Count) and Averages (Average Star Rating) based on your needs.

DeleteBooleanFeedback(int booleanFeedbackID)
This method will delete a feedback entry from the dataset based on the BooleanFeedbackID that each Boolean related feedback entry is marked with.

DeleteRatingFeedback(int ratingFeedbackID)
This method will delete a rating entry from the dataset based on the BooleanFeedbackID that each Boolean related feedback entry is marked with.
 

Object Types

BooleanFeedback

This object is used to save Boolean feedback into the Feedback API system. Note that the ReferenceName, FeedbackContentType and SubmissionType values are used as a Unique Key to group all feedback entries containing those values together. This grouping provides the ability to quickly retrieve data from the system as long as searches are done on the grouping values.

ReferenceName

A key to group your feedback data into, for example “BlogEntries”. This reference name should match the content reference name of the data you are posting feedback to but is not a requirement. If this is set to the same reference name feedback data will be available within the Agility Content Manager when viewing specific content item.

ContentType

The content type of the data you are providing feedback on, either WCM, UGC or Custom. Similarly to the reference name property you should set this properly to get data to appear properly within the Content Manager.

SubmissionType

The submission type is the specific Boolean feedback type you are trying to save. Possible Enum values are Like, Vote, ApproveDisapprove, Custom, and Count. Note that the feedback API can be used a custom counter when required using the Count Submission Type but count is currently not fully supported feedback type within the content manager.

RelatedContentID

This is the ID of the content that is receiving the feedback

IsPositive

The Boolean value to save for the current feedback entry. This value is only required to be set when the Submission Type is ApproveDisapprove, or Custom as all other types will automatically set this value to true (since all other types can be considered positive feedback entries)

BooleanFeedbackID

The ID that is set when a feedback entry is saved (Primary Key)

FeedbackTypeID

The Group ID of the feedback entry (this will be the same for all entries that have the same ReferenceName + ContentType + SubmissionType)

ProfileRecordID

The UGC Profile ID of the user who submitted the Feedback

ExternalProfileID

A custom string used to track which user submitted the feedback if not using UGC profiles

CreatedOn

Value the Feedback Entry was submitted

RequiresAuthentication

Value that defines if the Feedback Requires a user to be authenticated before submitting an entry.

SubmissionIntervalUnit

This property sets the interval unit when restricting the number of feedback entries per item is allowed per user. (hour, day, minute, etc)

SubmissionIntervalValue

The interval value to use along with the SubmissionIntervalUnit (1 day, 1 hour, etc)

 

RatingFeedback

This object is used to save rating feedback into the Feedback API system. Note that the ReferenceName, FeedbackContentType and SubmissionType values are used as a Unique Key to group all feedback entries containing those values together. This grouping provides the ability to quickly retrieve data from the system as long as searches are done on the grouping values.

 

ReferenceName

A key to group your feedback data into, for example “BlogEntries”. This reference name should match the content reference name of the data you are posting feedback to but is not a requirement. If this is set to the same reference name feedback data will be available within the Agility Content Manager when viewing specific content item

ContentType

The content type of the data you are providing feedback on, either WCM, UGC or Custom. Similarly to the reference name property you should set this properly to get data to appear properly within the Content Manager.

SubmissionType

The submission type is the specific Rating feedback type you are trying to save. Rating Feedback Types are only allowed to be a “Rating” or “Custom” SubmissionType. If this value is not set the value will default to “Rating” when calling SaveRatingFeedback().

RelatedContentID

This is the ID of the content that is receiving the feedback

RatingValue

The value to save as the rating for this feedback entry.

RatingFeedbackID

The ID that is set when a feedback entry is saved (Primary Key)

FeedbackTypeID

The Group ID of the feedback entry (this will be the same for all entries that have the same ReferenceName + ContentType + SubmissionType)

ProfileRecordID

The UGC Profile ID of the user who submitted the Feedback

ExternalProfileID

A custom string used to track which user submitted the feedback if not using UGC profiles

CreatedOn

Value the Feedback Entry was submitted

RequiresAuthentication

Value that defines if the Feedback requires a user to be authenticated before submitting an entry.

SubmissionIntervalUnit

This property sets the interval unit when restricting the number of feedback entries per item is allowed per user. (hour, day, minute, etc)

SubmissionIntervalValue

The interval value to use along with the SubmissionIntervalUnit (1 day, 1 hour, etc)

 

FeedbackSearchArgs

This object is used to build up search parameters to retrieve the feedback data you want for a specific item or group of items. This object lets you build rich search queries into your feedback data when trying to retrieve things like “number of likes”, “average rating value”, “sum of all rating values”, etc. This object also allows for date restrictions which are useful for reporting purpose, for example, “how many likes were added today”.

 

ReferenceName

The Reference Name of the Feedback Entries to search for.

ContentType

The Content Type of the Feedback Entries to search for. (WCM, UGC, or Custom)

SubmissionType

The SubmissionType of the Feedback Entries to search for.

RelatedContentIDs

The ID or List of IDs to retrieve the Aggregate data of. If this value is null or empty The Aggregate of all items within the “Reference Name + ContentType + SubmissionType” grouping will be returned.

StartDate

Starting date to limit the Feedback Entries to. If null then it will not limit the start date

EndDate

Ending date to limit the Feedback Entries to. If null then it will not limit the end date.

IsPositive

Check for Positive or Negative entries. Will only take effect on Boolean Feedback Types and should be null for Rating Feedback Types.

Action

The aggregate action to perform. Possible enum values Count, Sum and Average. Sum and Average only take effect on Rating Feedback Types and defaults to count if not set.

 

API Samples

The Voting and Rating API provides an Agility developer the ability to easily integrate Voting, Rating, Likes, Approval and Disapproval features against any piece of content within Agility’s content System. There are simple calls that are used to support adding and aggregating these values together.

Use the JavaScript API where possible.

JavaScript API

Agility.UGG.API.SaveRating(ratingFeedback, callback)
The SaveRating method will save a rating to the UGC system. This method expects a RatingFeedback object.
//ID of the content to related the rating to
var NewsID = 12345;
 
var RatingFeedback = new Agility.UGC.API.RatingFeedback();
RatingFeedback.ReferenceName = "NewsList";
RatingFeedback.ContentType = Agility.UGC.API.FeedbackContentType.WCM;
RatingFeedback.RelatedContentID = NewsID;
RatingFeedback.RatingValue = 3;
 
Agility.UGC.API.SaveRating(RatingFeedback, function (data) {
    alert("Rating Complete");
});
 
Agility.UGC.API.SaveLike(booleanFeedback, callback)
The SaveLike method call is used to save Likes on a related content item. This method expects a BooleanFeedback object.
 
var LikeFeedback = new Agility.UGC.API.BooleanFeedback();
LikeFeedback.ReferenceName = "RecordTypeName";
LikeFeedback.ContentType = Agility.UGC.API.FeedbackContentType.UGC;
LikeFeedback.RelatedContentID = 2825;
 
Agility.UGC.API.SaveLike(LikeFeedback, function (data) {
    if (data.ResponseType == Agility.UGC.API.ResponseType.OK) {
          alert("Like Successfully Saved");               
    }
 });
 
Agility.UGC.API.SaveVote(BooleanFeedback, Callback)
The SaveVote method call is used to save Votes on a related content item. This method expects a BooleanFeedback object.
 
var VoteFeedback = new Agility.UGC.API.BooleanFeedback();
VoteFeedback .ReferenceName = "RecordTypeName";
VoteFeedback .ContentType = Agility.UGC.API.FeedbackContentType.UGC;
VoteFeedback .RelatedContentID = 2825;
 
Agility.UGC.API.SaveVote(VoteFeedback, function (data) {
    if (data.ResponseType == Agility.UGC.API.ResponseType.OK) {
          alert("Vote Successfully Saved");               
    }
 });
 
Agility.UGC.API.SaveApproveDisapprove(booleanFeedback, IsApproved, callback)
The SaveApproveDisapprove method call is used to save "Approval" or "Disapproval" on a related content item. This method expects a BooleanFeedback object and if the value is positive or negative (IsApproved).
var ApprovalFeedback = new Agility.UGC.API.BooleanFeedback();
ApprovalFeedback .ReferenceName = "RecordTypeName";
ApprovalFeedback .ContentType = Agility.UGC.API.FeedbackContentType.UGC;
ApprovalFeedback .RelatedContentID = 2825;
 
//Save a Positive Feedback entry
Agility.UGC.API.SaveApproveDisapprove(ApprovalFeedback, true, function (data) {
    if (data.ResponseType == Agility.UGC.API.ResponseType.OK) {
          alert("Possitive Approval Successfully Saved");               
    }
 });
 
//Save a Negative Feedback entry
Agility.UGC.API.SaveApproveDisapprove(ApprovalFeedback, false, function (data) {
 if (data.ResponseType == Agility.UGC.API.ResponseType.OK) {
          alert("Negative Approval Successfully Saved");               
    }
 });
 
Agility.UGC.API.GetFeedbackAggregate(SearchArgs, Callback)
The GetFeedbackAggregate method is used to perform searches on the Feedback data added by the Save methods above. The SearchArg object is a FeedbackSearchArg object which allows filtering the search results or rolling up based on the parameters passed.
var search = new Agility.UGC.API.FeedbackSearchArg();
search.ReferenceName = "ContentReferenceName";
search.ContentType = Agility.UGC.API.FeedbackContentType.WCM;
search.SubmissionType = Agility.UGC.API.FeedbackSubmissionType.Like;
//array of ID's to look up
search.RelatedContentIDs[0] = 1234;
search.Action = Agility.UGC.API.AggregateTypes.Count;
 
Agility.UGC.API.GetFeedbackAggregate(search, function (data) {
      alert("Total Likes: " + data.ResponseData[0].Result);
});


Agility.UGC.API.SaveRating(ratingFeedback, Callback)
Saves a rating value.

var RatingFeedback = new Agility.UGC.API.RatingFeedback();
RatingFeedback.ReferenceName = "CustomTestRatingType";
RatingFeedback.ContentType = Agility.UGC.API.FeedbackContentType.WCM;
RatingFeedback.RelatedContentID = 123;
 
 RatingFeedback.RatingValue = 3;
 Agility.UGC.API.SaveRating(RatingFeedback, function (data) {
                alert("Rating complete: " + data.ResponseData);
});


Agility.UGC.API.SaveLike(booleanFeedback, Callback)
Saves a like.

var LikeFeedback = new Agility.UGC.API.BooleanFeedback();
LikeFeedback.ReferenceName = "MiskiwDataTypes";
LikeFeedback.ContentType = Agility.UGC.API.FeedbackContentType.UGC;
LikeFeedback.RelatedContentID = 2825;
 
//This line is only for demonstration purposes SaveLike() automatically sets this property
LikeFeedback.SubmissionType = Agility.UGC.API.FeedbackSubmissionType.Like;
 
 Agility.UGC.API.SaveLike(LikeFeedback, function (data) {
                    if (data.ResponseType == 0) {
                        alert("Like Has been saved: " +data.ResponseData);
                    }
});


Agility.UGC.API.SaveVote(booleanFeedback, Callback)
Saves a vote.

var VoteFeedback = new Agility.UGC.API.BooleanFeedback();
VoteFeedback .ReferenceName = "MiskiwDataTypes";
VoteFeedback .ContentType = Agility.UGC.API.FeedbackContentType.UGC;
VoteFeedback .RelatedContentID = 2825;
VoteFeedback .SubmissionType = Agility.UGC.API.FeedbackSubmissionType.Vote;
 
Agility.UGC.API.SaveVote(LikeFeedback, function (data) {
                    alert("Vote Saved: " +data.ResponseData);
 });


Agility.UGC.API.SaveApproveDisapprove(booleanFeedback, Callback)

Saves either an approval or disapproval. 

var ApprovalFeedback = new Agility.UGC.API.BooleanFeedback();
ApprovalFeedback .ReferenceName = "MiskiwDataTypes";
ApprovalFeedback .ContentType = Agility.UGC.API.FeedbackContentType.UGC;
ApprovalFeedback .RelatedContentID = 2825;
 
ApprovalFeedback .SubmissionType = Agility.UGC.API.FeedbackSubmissionType.ApproveDisapprove;
 
//Approve
Agility.UGC.API.SaveApproveDisapprove(LikeFeedback, true, function (data) {
                    alert(data.ResponseData);
                    LoadStats();
 });
 
//Disapprove
Agility.UGC.API.SaveApproveDisapprove(LikeFeedback, false, function (data) {
                    alert(data.ResponseData);
                    LoadStats();
});


Agility.UGC.API.GetFeedbackAggregate(feedbackSearchArgs, Callback)
Gets your count values for the given feedback type.

var search = new Agility.UGC.API.FeedbackSearchArg();
search.ReferenceName = "MiskiwUGCCommentLink";
search.ContentType = Agility.UGC.API.FeedbackContentType.WCM;
search.SubmissionType = Agility.UGC.API.FeedbackSubmissionType.Like;
search.RelatedContentID = [1837];
search.Action = Agility.UGC.API.AggregateTypes.Count;
 
Agility.UGC.API.GetFeedbackAggregate(search, function (data) {
                alert("Total Like Count: " +data.ResponseData[0]);
});

 

.NET API

It is highly recommended to use the JavaScript API for performance reasons, however, if you need to there is the following server to server API.

SaveRatingFeedback(DataServiceAuthorization auth, RatingFeedback feedback)
This method will save a RatingFeedback object to the Feedback API. The result will be an integer with the current RatingFeedbackID.
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
    
   RatingFeedback feeback = new RatingFeedback();
   feedback.RelatedContentID = 123;
   feedback.RatingValue = 3;
   feedback.ReferenceName = "BlogEntries";
   feedback.ContentType = FeedbackContentType.UGC;
   feedback.SubmissionType= FeedbackSubmissionType.Rating;
             
   int RatingFeedbackID = client.SaveRatingFeedback(auth, feedback)
 
   if (RatingFeedbackID >0) 
   {
     //Rating Successfully Saved
   }
}

 

SaveBooleanFeedback(DataServiceAuthorization auth, BooleanFeedback feedback)
This method will save a BooleanFeedback object to the Feedback API. The result will be an integer with the current BooleanFeedbackID.
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
    
   BooleanFeedback feeback = new BooleanFeedback ();
   feedback.RelatedContentID = 123;
   feedback.RatingValue = 3;
   feedback.ReferenceName = "BlogEntries";
   feedback.ContentType = FeedbackContentType.UGC;
   feedback.SubmissionType= FeedbackSubmissionType.Like;
             
   int BooleanFeedbackID = client.SaveBooleanFeedback(auth, feedback)
 
   if (BooleanFeedbackID > 0) 
   {
     //Rating Successfully Saved
   }
}
 
DeleteBooleanFeedback(DataServiceAuthorization auth, int booleanFeedbackID)
This method will remove a Boolean Feedback entry from the Feedback API.
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
    
   
             
   bool success = client.DeleteBooleanFeedback(auth, 321)
 
   if (success) 
   {
     //Boolean Feedback Deleted successfully
   }
}

 

DeleteRatingFeedback(DataServiceAuthorization auth, int ratingFeedbackID)
This method will remove a Rating Feedback entry from the Feedback API.
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
     
   bool success = client.DeleteRatingFeedback(auth, 321)
 
   if (success) 
   {
     //RatingFeedback Deleted successfully
   }
}

 

GetFeedbackAggregate(DataServiceAuthorization auth, FeedbackSearchArgs searchArg)
This method is used to perform searches on the feedback API and provide back rolled up aggregates of the data.

 

 

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.