Using Episerver Social for finding popular content

Overview

Enabling the content rating feature in your website can help collect valuable feedback from site visitors. The Episerver Social platform provides a powerful ratings and statistics system that enables site developers to allow users to submit their content ratings, which the Episerver Social platform then uses to tabulate rating statistics. The generated statistical data can be a useful tool in determining how useful the content on your site appears to site visitors. Also, less popular content may be a potential candidate for further improvement.

This blog illustrates how to collect content ratings from your site visitors then gather the tabulated rating statistical data using the Episerver Social RatingStatistics service to identify popular or less-popular content.

Prerequisites

Apply the Episerver.Social.Ratings.Site package available at the Episerver Nuget feed to your Episerver site. An Episerver Alloy site was used for developing the sample snippets in this article.

Collecting ratings from site visitors

Using the Episerver Alloy site for an example, let us say we want to allow site visitors (authenticated as well as anonymous) to rate the product pages (of page type ProductPage) that are present in the site.

The first step in collecting ratings is defining a rating scheme. You may want visitors to rate a product page using a combination of Like and Dislike buttons, or  collect ratings on a scale of 1 through 5, or a scale of 1 through 100 to represent percentages.

The next step is to compose a rating object and submit it to the Episerver Social Rating system. The Rating class is used to represent a rating. A rating instance is comprised of three parts.

1. The reference to the user rating the resource.

The Reference class in the Episerver Social platform refers to users or resources outside the platform. Some examples of a user reference are user names or unique user identifiers assigned by the user provider configured for your application. If your application has multiple user providers, the user reference scheme could be combination of the provider and user identifiers: Reference.Create($"user://{providerid}/{userid}").

You are free to come up with a reference scheme that best suits your needs for uniquely identifying resources external to Episerver Social. For more information on References, refer to the Reference and IDs section in the Episerver Social Developer Guide.

 2. The reference of the resource being rated.

Some examples of resource references are page or product identifiers assigned by your content repository, such as Reference.Create(currentPage.ContentGuid.ToString()).

 3. An integer value representing the rating.

For example, in the Like-Dislike case above, a rating value of 1 could be mapped to the Like button and a value of -1 or 0 could be mapped to the Dislike button.

Once you identify the various components of a rating, the next step is to submit the rating. A sample UI to collect a user feedback is shown below. If a page has never been rated, you may want to prompt an incoming visitor to be the first rater for that page.

A complete implementation of the UI is outside the scope of this blog, but you may refer to the Episerver Social Alloy repository that uses Episerver block types to render rating forms that can be used across different product pages. A snippet to submit ratings is shown below.

private Rating AddRatingForProduct(ProductPage currentPage, int ratingValue)
{
    var productReference = Reference.Create(currentPage.ContentGuid.ToString());
    Reference userReference = null;
    if (this.User.Identity.IsAuthenticated)
    {
        userReference = Reference.Create(this.User.Identity.Name);
    }
    else
    {
        userReference = Reference.Create(System.Guid.NewGuid().ToString());
    }

    var rating = new Rating(userReference, productReference, new RatingValue(ratingValue));

    return ratingService.Add(rating);
}

The code above allows anonymous visitors to rate the product page. Based on the requirements of your application, you may want to allow or disallow the submission of anonymous ratings.

The Episerver Social system restricts a user to rate a particular resource only once (although an existing user rating value for a resource can be updated). To allow multiple anonymous visitors to rate the same resource, the code above represents each anonymous rater with an internally generated unique identifier. Depending on your application, you could instead use a unique visitor ID (from a cookie, for example) to track anonymous raters.

Retrieve rating and statistics for a page

If a product page has been rated in the past, you may want to retrieve and display rating statistics that indicate the average rating of that page and the total number of existing ratings. The snippet below uses the Episerver Social RatingStatistics service to retrieve rating statistics for that page.

private RatingStatistics GetAverageRatingForProduct(ProductPage currentPage)
{
    var productReference = Reference.Create(currentPage.ContentGuid.ToString());

    var criteria = new Criteria<RatingStatisticsFilter>
    {
        Filter = new RatingStatisticsFilter
        {
            Targets = new List<Reference> { productReference }
        },
        PageInfo = new PageInfo { PageSize = 1 }
    };

    var ratingStatisticsPage = ratingStatisticsService.Get(criteria);
    return ratingStatisticsPage.Results.FirstOrDefault();
}

Note that the page size for the query above is set to a value of 1, since there can be at the most only one statistics generated for a given resource.

To display any previously submitted rating of the logged-in user for the product page they are currently visiting, use the Episerver Social Rating service as shown below to retrieve the existing rating.

private Rating GetUserRatingForProduct(ProductPage currentPage)
{
    Rating rating = null;

    if (this.User.Identity.IsAuthenticated)
    {
        var productReference = Reference.Create(currentPage.ContentGuid.ToString());
        var userReference = Reference.Create(this.User.Identity.Name);
        var criteria = new Criteria<RatingFilter>
        {
            Filter = new RatingFilter
            {
                Targets = new List<Reference> { productReference },
                Rater = userReference
            },
            PageInfo = new PageInfo { PageSize = 1 }
        };

        var ratingPage = ratingService.Get(criteria);
        rating = ratingPage.Results.FirstOrDefault();
    }

    return rating;
}

Retrieve popular content in your site

The RatingStatistics service can be used to retrieve a page of rating statistics sorted by the mean rating value in an order from highest to lowest. The product pages that appear higher up in the page can be perceived as items that were more appealing or popular amongst site visitors. Items lower down in the list could be perceived as less attractive to visitors and thereby could be potential candidates for further tweaking or enhancements.

For example, if ratings have been submitted for the various product pages in an Episerver Alloy site, you could present the tabulated rating statistics for these pages (possibly in a site administrator view of your site) as shown in the picture below.

You could infer from the view above that the Alloy Meet product seems to be more appealing to visitors than other products and the Alloy Track product may need to be revisited to catch the eye of visitors.

The RatingStatistics service exposes a Get method that can be used to easily collect the information required to display the view above. A sample snippet is below.

private ResultPage<RatingStatistics> GetPopularProducts()
{
    var criteria = new Criteria<RatingStatisticsFilter>
    {
        PageInfo = new PageInfo { PageSize = 10, PageOffset = 0 },
        OrderBy = new List<SortInfo>
        {
            new SortInfo(RatingStatisticsSortFields.Mean, false)
        }
    };

    var ratingStatisticsPage = ratingStatisticsService.Get(criteria);
    return ratingStatisticsPage;
}

The above sample retrieves the first page of 10 rating statistics from the repository sorted by the average rating value in the order of highest to lowest. To retrieve subsequent pages of statistics, use the PageInfo property of the criteria object.

Refer to the PageInfo and Best practices for paginating results sections in the Episerver Social Developer Guide for more information on the paging feature of the Episerver Social APIs.

A gist with the source of the sample product controller used in this article can be found here:
https://gist.github.com/epishilpa/94e49d0f927e149502fd738a1fd4bf2f.

Remarks

The RatingStatistics service also exposes an Update API that allows adding additional data to ratings statistics that were internally calculated for a resource. If your business needs require the presence of supplemental statistical data, you can attach it as extension data to the statistics generated by Episever Social. If you choose to do so, the GetPopularProducts method can be updated to use another overload of the Get API that allows retrieving and filtering by extension data.

For more information on the extending rating statistics with extension data, refer to the Extending ratings with composites section of the Episerver Social Developer Guide.