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
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
//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"); });
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"); } });
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"); } });
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"); } });
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.
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 } }
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 } }
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 } }
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.
Comments
Please sign in to leave a comment.