Skip navigation

Enable content personalization with artificial intelligence

Get personalized content using our integrated Smart Recommendations engine, powered by RecombeeOpens in a new window. The engine uses machine learning to analyze your content and (optionally) user behavior. This way it learns which pieces of content work well together and what content is most relevant for a specific audience.

To use Smart Recommendations, you need to do two things: 1. set up your Kontent project and 2. set up your app to recommend content. Learn how to recommend specific content to specific visitors.

Smart Recommendations is in Beta and its behavior may change in the future.

Table of contents

    How does content recommendation work?

    Here's an example of what happens when a visitor comes to your website and views an article. In this example, John, who's a returning visitor, wants to read an article about CaaS. He's reading through the article and the website shows him related articles he might be interested in. The whole process boils down to four steps.

    A diagram explaining content recommendation from a website to a recognized visitor.

    Content recommendation in a nutshell.

    For new visitors, the process is the same. They just get more general recommendations compared to visitors with a browsing history.

    Smart Recommendation benefits

    • Real time recommendations – The engine learns from every step your visitors take. For example, it can track how often and what type of content your visitors see and use the information for better recommendations.
    • Domain independence – The engine is being successfully used to recommend news, cultural events, books, medical products, job offerings, and more. It will adapt to your domain as well. 
    • Flexible and extensible – Provide more specific recommendations by using advanced techniques such as filtering, boosting, or more granular visitor tracking.
    • Continuous improvement – The algorithms used by Smart Recommendations are managed, tested, and improved through machine learning. Your recommendations models are updated in real-time.

    Set up recommendations for your project

    1. Activate Smart Recommendations

    Smart Recommendations is an additional feature of Kentico Kontent purchased separately. To enable it for your account, contact us using at bottom right (or click the button below) and let us know the details. We'll enable Smart Recommendations for you.

    Request Smart Recommendations

    After activation, you'll see the Smart Recommendations icon in the app menu on the left.

    2. Register your project

    In , click Register your project with Smart Recommendations.

    3. Save your Setup Password

    After registering your project, Smart Recommendations will generate a Setup Password for you. This password is required every time you want to access Smart Recommendations in Kontent.

    Warning

    If you lose the Setup Password, you won't be able to use and configure Smart Recommendations! This is NOT an API key.

    A screenshot of the Setup Password screen.

    4. Choose the types of content to recommend

    Let Smart Recommendations know the types of content items it should index and recommend. For example, you might want to recommend articles or blog posts but not landing pages. This process doesn't affect your existing content.

    1. In , find the Content types to recommend card and click Register content type.
    2. Select a content type such as Article from the list.
    3. Click Add.
    4. In the Register new content type popup, provide your Setup Password.
    5. Click Save.

    The engine now retrieves all content items based on the registered type and stores it in its own database. It doesn't do any content updates or checks on its own.

    5. Ensure up-to-date recommendations

    To keep the recommendation database in sync with changes in your content:

    1. Create a new webhook with the following properties:
      • Webhook name: Update recommendations
      • URL address: https://recommend.kontent.ai/update-content
      • Triggers: Keep defaults.
    2. For your new webhook Secret, click .
    3. In , click Add your webhook secret.
    4. In the Webhook secret popup, provide your new webhook secret and Setup Password.
    5. Click Save.

    Now that you have your project set up for Smart Recommendations, continue with setting up your app.

    Tip: Let editors and marketers tailor the recommendations

    Visualize the recommendation settings for business users by adding a custom element for Smart RecommendationsOpens in a new window.

    Smart Recommendation settings visualized through a custom element.

    Set up your app for recommendations

    To add content recommendations to your app, use the Smart Recommendation API together with Delivery API. The Smart Recommendations API returns only the codenames of the recommended content items. You then use these codenames to get specific items through the Delivery API.

    1. Get the Smart Recommendations API key

    To use the API, you need an API key that's available in Smart Recommendations in Kontent. Make sure you have your Setup Password ready.

    In > Smart Recommendation API card > Click for the API key.

    Use the API key to send a POST request to get a list of recommended items from the Smart Recommendations API. In the request body, specify the following properties:

    • Visit ID – Identifies the visitor.
    • The current item's codename – Identifies the content item that the visitor sees at the moment.
    • The response limit – Tells the API how many items you want to recommend to the visitor.
    • The requested content type codename – Tells the API what type of items you want to recommend.

    For example, here is how you get three recommended articles for John, who's currently reading an article about CaaS.

    • JavaScript
    // Tip: Find more about JS/TS SDKs at https://docs.kontent.ai/javascript import { RecommendationClient } from '@kentico/kontent-recommendations'; const client = new RecommendationClient({ projectId: '<YOUR_PROJECT_ID>', apiKey: '<YOUR_SMART_RECOMMENDATION_API_KEY>' }); await client.recommendItems() .withData({ visitId: 'visitorJohn', // Visitor identified as John currentItemCodename: 'caas', // Visitor is reading CaaS responseLimit: 3, // You want three recommendations requestedTypeCodename: 'blog_post' // You want articles }).toPromise();
    // Tip: Find more about JS/TS SDKs at https://docs.kontent.ai/javascript import { RecommendationClient } from '@kentico/kontent-recommendations'; const client = new RecommendationClient({ projectId: '<YOUR_PROJECT_ID>', apiKey: '<YOUR_SMART_RECOMMENDATION_API_KEY>' }); await client.recommendItems() .withData({ visitId: 'visitorJohn', // Visitor identified as John currentItemCodename: 'caas', // Visitor is reading CaaS responseLimit: 3, // You want three recommendations requestedTypeCodename: 'blog_post' // You want articles }).toPromise();
    • C#
    // Tip: Find more about .NET SDKs at https://docs.kontent.ai/net using Kentico.Kontent.Recommendations; using Kentico.Kontent.Recommendations.Models; // Creates an instance of the recommendation client var recommendationClient = new RecommendationClient(accessToken: "<YOUR_RECOMMENDATION_API_KEY>", timeoutSeconds: 5); // Creates a new recommendation request var recommendationRequest = new RecommendationRequest { VisitId = "visitorJohn", // Visitor identified as John CurrentItemCodename = "caas", // Visitor is reading CaaS ResponseLimit = 3, // You want three recommendations RequestedTypeCodename = "article" // You want articles }; // Gets the recommendations (codenames of the recommended items) RecommendedContentItem[] recommendedArticles = await recommendationClient.GetRecommendationsAsync(recommendationRequest);
    // Tip: Find more about .NET SDKs at https://docs.kontent.ai/net using Kentico.Kontent.Recommendations; using Kentico.Kontent.Recommendations.Models; // Creates an instance of the recommendation client var recommendationClient = new RecommendationClient(accessToken: "<YOUR_RECOMMENDATION_API_KEY>", timeoutSeconds: 5); // Creates a new recommendation request var recommendationRequest = new RecommendationRequest { VisitId = "visitorJohn", // Visitor identified as John CurrentItemCodename = "caas", // Visitor is reading CaaS ResponseLimit = 3, // You want three recommendations RequestedTypeCodename = "article" // You want articles }; // Gets the recommendations (codenames of the recommended items) RecommendedContentItem[] recommendedArticles = await recommendationClient.GetRecommendationsAsync(recommendationRequest);
    • cURL
    curl --request POST \ --url https://recommend.kontent.ai/api/v2/recommend/items \ --header 'Authorization: Bearer <YOUR_SMART_RECOMMENDATIONS_API_KEY>' \ --header 'Content-type: application/json' --data ' { "visitId": "visitorJohn", "currentItemCodename": "caas", "responseLimit": 3, "requestedTypeCodename": "article", }'
    curl --request POST \ --url https://recommend.kontent.ai/api/v2/recommend/items \ --header 'Authorization: Bearer <YOUR_SMART_RECOMMENDATIONS_API_KEY>' \ --header 'Content-type: application/json' --data ' { "visitId": "visitorJohn", "currentItemCodename": "caas", "responseLimit": 3, "requestedTypeCodename": "article", }'

    By default, getting a list of recommended items for a visitor is also tracked as a visit of the item. Automatic tracking can be turned off with manual tracking.

    When recommending content to your visitors, you can also use advanced techniques like filtering and boosting. These methods let you omit some items while preferring others. Find detailed information on how to adjust what recommendations you get.

    Do this when getting data from the API

    1. Go async – Request and display your recommendations in an asynchronous way so that it doesn't block the rest of your app. For example, you can do this with AjaxOpens in a new window calls.
    2. Implement failover – In case the API doesn't respond in time or with enough items to recommend, make sure your app handles it gracefully. For example, display a prepared message instead.

    Track more to recommend better content

    By default, Smart Recommendations is set to track content visits automatically. This means it only tracks which visitor saw which content item whenever you request recommendations.

    For boosting the relevance of your recommendations, consider manually tracking events and visitor information from your app.

    • Geolocation – Know where your visitors are. This lets you recommend content specific to their region. Geolocation is available out-of-the-box.
    • Partial views – Know how far your visitors scrolled, that is what portion of your content they viewed. This lets you recommend content they're more interested in.
    • Conversions – Know whether your visitors performed specific actions you seek. This lets you segment your visitors into groups or personas.
    • Custom dimensions – Track any custom metric, for example, whether visitors used search.

    To track these kinds of information and interactions, you need to send tracking requests to the Smart Recommendations API from your app. You can find request samples in the API reference.

    Once your app is set up, go to and enable Manual tracking. This disables automatic content visit tracking.

    Track users automatically with CookieHelper

    If you'd like to automate actions like tracking users, generating visit identifiers, getting referrers, IP addresses, or location data, we recommend using the CookieHelper extensionOpens in a new window. For tracking location data, make sure you enable Geolocation in for your project.

    The CookieHelper extension provides a helper class that lets you distinguish your visitors and track additional details about them.

    It works with the .NET Core Request and Response objects and uses cookies to track the visitors. Keep in mind that you may be legally obliged to disclose this information to your visitors and let them disable the tracking cookies.

    • C#
    // Tip: Find more about .NET SDKs at https://docs.kontent.ai/net using Kentico.Kontent.Recommendations; using Kentico.Kontent.Recommendations.CookieHelper; // Tries to get a cookie, which stores the visitId var cookie = RecommendationCookieHelper.GetRecommendationTrackingCookie(Request); // If there's no cookie, the visitor is new and without a visitId if (cookie == null) { // Creates a new tracking cookie for the visitor cookie = RecommendationCookieHelper.SetNewRecommendationTrackingCookie(Request, Response); } // Creates an instance of the recommendation client var recommendationClient = new RecommendationClient(accessToken: "<YOUR_RECOMMENDATION_API_KEY>", timeoutSeconds: 5); await recommendationClient.CreateVisitorAsync( cookie.VisitId, // Provides the generated visitId cookie.GetVisitorDetails(Request) // Provides IP address and referrer );
    // Tip: Find more about .NET SDKs at https://docs.kontent.ai/net using Kentico.Kontent.Recommendations; using Kentico.Kontent.Recommendations.CookieHelper; // Tries to get a cookie, which stores the visitId var cookie = RecommendationCookieHelper.GetRecommendationTrackingCookie(Request); // If there's no cookie, the visitor is new and without a visitId if (cookie == null) { // Creates a new tracking cookie for the visitor cookie = RecommendationCookieHelper.SetNewRecommendationTrackingCookie(Request, Response); } // Creates an instance of the recommendation client var recommendationClient = new RecommendationClient(accessToken: "<YOUR_RECOMMENDATION_API_KEY>", timeoutSeconds: 5); await recommendationClient.CreateVisitorAsync( cookie.VisitId, // Provides the generated visitId cookie.GetVisitorDetails(Request) // Provides IP address and referrer );

    What's next?