Set up recommendations

Estimated duration: 15-30 minutes

Introduction

Prepr allows you to add recommendations to your web application quickly. This tutorial demonstrates how to deliver recommendations using the Prepr GraphQL API. Follow the step-by-step guide below.

Use case

Deliver highly relevant content recommendations to the visitors of your websites and apps using the GraphQL API to increase engagement. Let's examine an everyday use case: an article that you want to show recommendations for.

drawing

Recommendations are usually displayed below an article to entice visitors to view more content. With Prepr, you can display two types of recommendations:

  • Similar items
  • Popular items

Similar items

Similar items are recommendations similar to the article the visitor is currently viewing. Because it's on the same topic, or because it's by the same author, or maybe it's approximately the same length.

With this recommendation type, the algorithm looks at the characteristics of the article (content, meta-data, links to other articles, etc.) and determines what the most relevant related articles are based on a score.

Popular items, the name says it all, are the most viewed items. The algorithm looks at how often an item has been viewed for this recommendation type. You could say this is not a recommendation but sorting by popularity.

Content structure

Before you start generating the recommendations, it’s a good idea to look at the content model of the article. That structure largely determines how accurate the recommendations become.

Recommendations-popular-items

In this case you have an article with a number of content fields: title, intro and content. In addition, there are references to an author and to one or more categories. And finally, an editor can manually add tags. Prepr uses all this information to provide the most relevant recommendations.

Creating a Prepr CMS account

Note

You can skip this step if you already have a Prepr CMS account with models and content items.

Following this guide requires a (free) Prepr CMS account.

Querying the API for similar items

To retrieve similar items, you must first have the ID of the content item where you want to show recommendations for:

Getting a content item ID

  • Go to the Content tab.
  • Open a content item and copy the ID:

Content item ID

Retrieving similar items

  • Go to Settings > Access tokens.
  • Click to open the GraphQL Published token details.
  • Open the API explorer.

API Explorer

View the API reference for all API authentication details

  • Add the following query to the explorer:
query {
 Similar_Articles(
   id: "0cbe2455-124c-4820-b2ac-dcc4261e150c"
 ) {
   items {
     _id
     title
   }
 }
}
  • Replace the id value with the ID of your content item

Note the Similar_Articles query type at the beginning of the query. For each content model in your environment the Prepr creates a corresponding GraphQL type with a similarity algorithm. The plural type name of the content model is prefixed with Similar_. For example Article generates a type Similar_Articles. You can find all these options in the API Explorer.

  • Run the query

The result should look something like:

{
 "data": {
   "Similar_Articles": {
     "items": [
       {
         "_id": "885b71ac-5a4b-4d2e-9770-a4a6f20425e9",
         "title": "15 Tips On How To Brand Yourself Online"
       },
       {
         "_id": "f1d9b142-883f-4964-8d8f-cd2f255330a2",
         "title": "Why Customization Is Key For Entrepreneurs In The Digital Age"
       },
       {
         "_id": "dd42b8c4-4773-4fdd-a71f-87e57b35beaa",
         "title": "Building User Trust In UX Design"
       },
       {
         "_id": "79c453ed-ffe2-4aec-8fb2-f549e3775264",
         "title": "Building A Video Streaming App With Nuxt.js"
       },
       {
         "_id": "5a53b271-898e-4eef-b877-5863b34b6ff9",
         "title": "UI Design Testing Tools I Use All The Time"
       },
       {
         "_id": "ca0e0d37-600b-42f7-a013-9b0f8e18f127",
         "title": "The Evolution Of Jamstack"
       },
       {
         "_id": "dd3309eb-df84-4e4b-8fdf-80b31b8eb58a",
         "title": "The Rise Of Design Thinking As A Problem Solving Strategy"
       },
       {
         "_id": "f4b65d11-c2e2-4320-a363-e7d420d03ed2",
         "title": "Modeling A GraphQL API For Your Blog"
       }
     ]
   }
 }
}

That's all. You now have recommendations that you can show in your application. Let's see how we can improve the recommendations even more.

Filtering the result

The previous example included all items for determining recommendations. But often, you want to make the result even more accurate. For example, you may want to query only recommended articles published recently or in a particular category.

So let's see how you can do that.

  • Expand the query with the following parameters:
query {
 Similar_Articles(
   id: "0cbe2455-124c-4820-b2ac-dcc4261e150c"
   where: {
     _publish_on_gt: "2021-01-01T00:00:00+00:00"
     categories: {
       _slug_any: [
         "ux-design", "development"
       ]
     }
   },
   limit: 3
 ) {
   items {
     _id
     title
   }
 }
}
  • We added _publish_on_gt: "2021-01-01T00:00:00+00:00" to show only articles published after January 1, 2021. Note the underscore at the beginning of the parameter.
  • We added categories: { _slug_any: [ "ux-design", "development" ] } to limit the result to only articles in the “UX Design” or the “Development” categories. Note the square brackets because we’re dealing with an array.
  • We added limit: 3 to limit the number of results to three items

The result should look something like:

{
 "data": {
   "Similar_Articles": {
     "items": [
       {
         "_id": "dd42b8c4-4773-4fdd-a71f-87e57b35beaa",
         "title": "Building User Trust In UX Design"
       },
       {
         "_id": "5a53b271-898e-4eef-b877-5863b34b6ff9",
         "title": "UI Design Testing Tools I Use All The Time"
       },
       {
         "_id": "dd3309eb-df84-4e4b-8fdf-80b31b8eb58a",
         "title": "The Rise Of Design Thinking As A Problem Solving Strategy"
       }
     ]
   }
 }
}

View the API reference for all filter options.

Optimizing the recommendation algorithm

You can tweak the recommendation algorithm further if you want more control over the results.

Prepr uses three parameters to determine recommendations: Entities, Tags, and References.

  • Entities - Prepr uses AI Text Analysis to determine what an article is about by automatically extracting entities from the text.
  • Tags - Prepr uses the tags associated with an article.
  • References - Prepr uses an item's relationship with other content items. So in this example, Prepr looks at other articles in the same category and articles by the same author.

By default, Prepr uses all three parameters to determine recommendations, but you can change that and specify the weight of each parameter.

Here’s an example of how that works:

query {
 Similar_Articles(
   id: "0cbe2455-124c-4820-b2ac-dcc4261e150c"
   where: {
     _publish_on_gt: "2021-01-01T00:00:00+00:00"
     categories: {
       _slug_any: [
         "ux-design", "development"
       ]
     }
   },
   limit: 3
   rules: {
     entities: 1
     tags: 0
     references: 0.5
   }
 ) {
   items {
     _id
     title
   }
 }
}
  • We added rules: { entities: 1, tags: 0, references: 0.5 } to indicate that tags should not be included and that references count for half. Note that the commas are optional.

We recommend starting with the default setting and adding rules only if the result does not meet your expectations.

View the API reference for all rules options.

To show the most popular items, you must track how often visitors view content items. That information can be used to display the most popular items.

Capturing views

Prepr uses a lightweight piece of javascript to capture events: the Prepr tracking code.

  • Add the Prepr tracking code to the <head> section of your website
<!-- Prepr Tracking Code -->
<script >
  ! function (e, t, p, r, n, a, s) {
    e[r] || ((n = e[r] = function () {
        n.process ? n.process.apply(n, arguments) : n.queue.push(arguments)
    }).queue = [], n.t = +new Date, (a = t.createElement(p)).async = 1, a.src = "https://cdn.tracking.prepr.io/js/prepr.min.js?t=" + 864e5 * Math.ceil(new Date / 864e5), (s = t.getElementsByTagName(p)[0]).parentNode.insertBefore(a, s))
  }(window, document, "script", "prepr"), prepr("init", "<YOUR-ACCESS-TOKEN>"), prepr("event", "pageload");
</script>
  • Replace with the GraphQL access token in your account: Settings > Access tokens.
  • Add the following HTML tag to start capturing views. Add the following meta tag to the <head> section of content pages. Use the content item ID as the value for the content property.
<meta property="prepr:id" content="16c63a1e-e837-4951-bd9a-b933a8d14b2f"/>
  • Test the capturing of page views by visiting a content page. Then check the content item in Prepr to see if Prepr registered the engagement.

Check engagement

View the API reference for all tracking options.

Now that you’re tracking how often visitors view an item, you can retrieve the most popular items.

  • Go to Settings > Access tokens.
  • Click to open the GraphQL Published token details.
  • Open the API explorer.

API Explorer

View the API reference for all API authentication details

  • Add the following query to the explorer:
query {
 Popular_Articles {
   items {
     _id
     title
     _views
   }
 }
}
Note the **Popular_Articles** query type at the beginning of the query. Prepr automatically provides you with a popularity query for each model. If your model name is Article, you also get the Popular_Articles query. You can find all these query options in the API explorer.

Note the _views system field that shows the number of views for a content item. This field is optional. We recommend not using it to optimize cache efficiency.

The result should look something like this:

{
 "data": {
   "Popular_Articles": {
     "items": [
       {
         "_id": "0cbe2455-124c-4820-b2ac-dcc4261e150c",
         "title": "How to set up a Google Ads account",
         "_views": 83
       },
       {
         "_id": "dd42b8c4-4773-4fdd-a71f-87e57b35beaa",
         "title": "Building User Trust In UX Design",
         "_views": 59
       },
       {
         "_id": "79c453ed-ffe2-4aec-8fb2-f549e3775264",
         "title": "Building A Video Streaming App With Nuxt.js",
         "_views": 49
       },
       {
         "_id": "5a53b271-898e-4eef-b877-5863b34b6ff9",
         "title": "UI Design Testing Tools I Use All The Time",
         "_views": 40
       },
       {
         "_id": "dd3309eb-df84-4e4b-8fdf-80b31b8eb58a",
         "title": "The Rise Of Design Thinking As A Problem Solving Strategy",
         "_views": 29
       },
       {
         "_id": "f1d9b142-883f-4964-8d8f-cd2f255330a2",
         "title": "Why Customization Is Key For Entrepreneurs In The Digital Age",
         "_views": 21
       },
       {
         "_id": "885b71ac-5a4b-4d2e-9770-a4a6f20425e9",
         "title": "15 Tips On How To Brand Yourself Online",
         "_views": 11
       },
       {
         "_id": "ca0e0d37-600b-42f7-a013-9b0f8e18f127",
         "title": "The Evolution Of Jamstack",
         "_views": 9
       },
       {
         "_id": "f4b65d11-c2e2-4320-a363-e7d420d03ed2",
         "title": "Modeling A GraphQL API For Your Blog",
         "_views": 5
       }
     ]
   }
 }
}

Filtering the result

The previous example included all items for retrieving the most popular items. But often, you want to make the result even more accurate. For example, only show items published recently or in a particular category.

So let's see how you can do that.

  • Expand the query with the following parameters:
query {
 Popular_Articles(
   where: {
     _publish_on_gt: "2021-01-01T00:00:00+00:00"
     categories: {
       _slug_any: [
         "ux-design", "development"
       ]
     }
   },
   limit: 3
 ) {
   items {
     _id
     title
     _views
   }
 }
}
  • We added _publish_on_gt: "2021-01-01T00:00:00+00:00" to show only articles published after January 1, 2021. Note the underscore at the beginning of the parameter.
  • We added categories: { _slug_any: [ "ux-design", "development" ] } to limit the result to only articles in the “UX Design” or the “Development” categories. Note the square brackets because you’re dealing with an array.
  • We added limit: 3 to limit the number of results to three items.

Result:

{
 "data": {
   "Popular_Articles": {
     "items": [
       {
         "_id": "dd42b8c4-4773-4fdd-a71f-87e57b35beaa",
         "title": "Building User Trust In UX Design",
         "_views": 59
       },
       {
         "_id": "79c453ed-ffe2-4aec-8fb2-f549e3775264",
         "title": "Building A Video Streaming App With Nuxt.js",
         "_views": 49
       },
       {
         "_id": "5a53b271-898e-4eef-b877-5863b34b6ff9",
         "title": "UI Design Testing Tools I Use All The Time",
         "_views": 40
       }
     ]
   }
 }
}

Want to learn more?

Check out the following chapters:

Schedule a free consultation

Do you want to get started with recommendations but still have questions or want a demo? Then, make an appointment with a Prepr solution engineer right away.