Personalizing content with smart recommendations

Get personalized content using our integrated recommendation engine. When you have a lot of content, you'll often want to provide recommended content to specific groups of users. It can be very demanding to anticipate everything your users might want and create complex rules to deliver the right content.

Premium feature

The Recommendation API requires an Enterprise plan. See Pricing for more details.

Table of contents

    Recommendation API is in Beta

    This feature is in Beta and its behavior may change in the future.

    Rather than categorizing all of your content yourself in terms of both the content and your users, you can call the Kentico Cloud Recommendation API when you want to recommend content that is stored in Kentico Cloud. The API will use an integrated recommendation engine to autonomously recommend relevant content items for your visitors and the content they are currently visiting.

    The engine uses machine learning to analyze your content and (optionally) visitor behavior to learn which pieces of content work well together and what content is most relevant for a specific audience. This helps you deliver content that is personalized.

    To use the API you need only a single API call to get your recommendations. All the tracking and decision making is made by the underlying artificial intelligence.

    Features

    • Real-time recommendation as a service
      Our API/.NET SDK returns recommendations immediately after a visitor performs any action on your website or in your app.
    • Domain independence
      The underlying recommendation system is currently successfully being used to recommend news, cultural events, books, medical products, job offerings, and much more. It is easily adaptable to any domain.
    • Research and improvements
      The machine learning algorithms are continuously managed, tested, and improved through artificial intelligence.
    • Flexibility and optimization
      You can take advantage of the many options to customize the recommendations through filtering or boosting your results.
    • Optional event tracking
      Track all the different actions your visitors take on your website/in your app to make your recommendations even better.

    How does it all work together?

    1. A visitor arrives at your website/opens your application.
    2. Immediately, you request recommended content for this user by calling the Recommendation API. You provide the API:
      1. Identification of the user (hash/token id and optionally location, device, etc.).
      2. What content they are currently viewing.
      3. How many content items of a specific content type you want to recommend.
    3. The AI processes all the information and decides (based on other content interactions and content similarity) what additional content your visitor might be interested in.
    4. In the response, you receive a list of items to be recommended to the current visitor.

    Setting up recommendations

    Recommendations are tied to content types - you select what type of content items you want to recommend. When you send requests for recommendations, your users' interactions with various items are tracked, leading to recommendations for the best items for the current visitor and content item.

    As this feature is currently in Beta, one of our developers has to set up the system for you. To do so, you will need to provide:

    • Your Project ID
    • A list of the content types you want to recommend
    • A list of the properties of each content type you want the AI to take into account for content recommendations.

    Contact us using the chat button in the bottom right with all of this info and we'll set up your recommendation database, populate it with already published content, and send you an authentication key for the Recommendation API.

    Then you'll be able to request content recommendations through our SDK or direct requests to the API.

    There are currently two ways for you to access content recommendations:

    1. KenticoCloud.Recommender for netstandard 2.0
    2. KenticoCloud.Recommender.MVC for .NET MVC 4.61
    3. Connect directly to the Recommendation API
      If you prefer this approach, you can connect to the API from any REST client. Just don't forget the authentication key and the correct token authentication header. See our API reference for more details.

    You can create a webhook pointing at one of our services that will handle automatic updates for all your recommended content. This will allow you to recommend new content immediately after it is published. Webhook creation is part of the process of registering for recommendations, so you don't need to implement anything, just register the correct address in your Kentico Cloud application.

    Getting recommended articles

    The code below shows how to get 2 recommended articles for a visitor who is currently reading the {~current_codename~} article.

    • C#
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", limit: 2); // or more fluently var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article").Execute();
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", limit: 2); // or more fluently var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article").Execute();

    Suggestions for implementation

    Always call the API asynchronously and set up a timeout for your client. The API is in beta and it can occasionally take a longer time to get your response – don't let it ruin your viewers' experience.

    When using MVC, we highly recommend rendering recommendations asynchronously with an Ajax call while the rest of the page is rendered independently.

    You can also filter and boost the recommended results to customize what is recommended. The example below returns only articles that are tagged as for a specific persona while also making it more likely for newer articles to be recommended.

    • C#
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var lastMonth = TimeSpan.FromDays(30).Milliseconds; var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", filterQuery: "\"personas=Barista\" in "properties"", boosterQuery: $"if "lastupdated" >= now() - {lastMonth} then 2 else 1", limit: 2); // or more fluently var recommendedArticles = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article") .WithBoosterQuery($"if "lastupdated" >= now() - {lastMonth} then 2 else 1") .WithFilterQuery("\"personas=Barista\" in "properties"") .Execute();
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var lastMonth = TimeSpan.FromDays(30).Milliseconds; var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", filterQuery: "\"personas=Barista\" in "properties"", boosterQuery: $"if "lastupdated" >= now() - {lastMonth} then 2 else 1", limit: 2); // or more fluently var recommendedArticles = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article") .WithBoosterQuery($"if "lastupdated" >= now() - {lastMonth} then 2 else 1") .WithFilterQuery("\"personas=Barista\" in "properties"") .Execute();

    If proper use of filtering and boosting seems advanced and complicated, don't hesitate to contact us and we will help you with your filters/boosters. We will create more detailed documentation on this subject as the feature develops.

    Tracking events (optional)

    Simply requesting a recommendation will track a default interaction between the visitor and content (a visit), but you can also log visitor–content interactions yourself. You can use the same SDK/API you're already using for the recommendations – see the API reference for details.

    There are 3 types of interactions that can be logged:

    1. Visit – a standard page visit.
    2. Conversion – a further unspecified visitor action that benefits your business in some way (such as a purchase or form submission).
    3. Portion View – an optional call that specifies how much of the page the current visitor has already read. Partial views may be logged multiple times during a single page visit as the visitor scrolls down the page – the engine will use only the last view. Although it may be more challenging to implement this feature, using it will further improve your recommendations.

    If you're using the SDK and want to use these tracking features, you need to alter your GetRecommendations call a little by providing it with a separateTracking=true option.

    • C#
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", limit: 2, separateTracking: true); // or more fluently var recommendedArticlesFluent = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article") .WithSeparateTracking() .Execute();
    var recommendationClient = new RecommendationClient("recommendation_token", 5); var recommendedArticles = await recommendationClient.GetRecommendationsAsync( "current_codename", Request, Response, contentType: "article", limit: 2, separateTracking: true); // or more fluently var recommendedArticlesFluent = await recommendationClient.CreateRequest( Request, Response, "current_codename", limit: 2, contentType: "article") .WithSeparateTracking() .Execute();

    Contact us

    If you need any help with content recommendation or have any questions or requests regarding this documentation, please contact us using the chat button in the bottom right.