Inline Content Recommendations

Learn how to add seamless content recommendations to your website fueled by Lytics' Content Affinity Engine; all it takes is an API request and a little HTML.

Difficulty: Beginner

TLDR: Here's some docs instead.

Other resources:

• A blog post - covering basically the same thing - with a live example!
• Lytics Segment API Docs (for segment creation API and SegmentQL)

Prerequisites

• Lytics Javascript Tag installed on your website.
• Pathfora SDK installed on your website. If you're using Lytics for personalized modals, this is already done for you!
• Content classified in your Lytics account (go to the content section of your Lytics account to check if we've classified your content).
• A valid API token for your Lytics account (learn about managing API tokens). For ease of use we suggest adding as an environment variable in your command line:

export LIOKEY={API Token}

1. Build a Content Collection

Before we go crazy adding recommendations to your website we should think about what kind of content we want to allow for recommendation. Lets create a dynamic set of content that will be the target pool of documents for this content recommendation block.

To do this, we can use the Lytics Segment API create endpoint.

curl -s -XPOST "https://api.lytics.io/api/segment" \
  -H "Content-type: text/plain" \
  -H "Authorization: $LIOKEY" \
  -d '
FILTER AND (
  path CONTAINS "froyo/flavors"
)
FROM content
ALIAS froyo_content
' | jq '.'

In the command above, we made a POST request to create a new segment on the content table, or as we call it - a content collection. We used Segment QL to define the filter on the content in your account. In the example above, we're only accepting urls that contain the path froyo/flavors. Simple enough, right? If you've used the Audience builder you may notice that the logic for building a segment is essentially the same format.

Here's a more complex example:

FILTER AND (                    // AND operator on the following statements
  global CONTAINS "strawberry"  // require the topic strawberry
  global CONTAINS "vanilla"     // require the topic vanilla
  path CONTAINS "posts"         // url must contain the path "/posts/"
  published > now-30d           // require published in the last 30 days 
)
FROM content                    // entities from the content table
ALIAS strawberry_vanilla        // saved name of the collection

You're probably wondering where these field names are coming from! These are the standard fields used in our content table. Here's a list of relevant fields you might use in building a content collection:

Also if you have access to your queries in the Data tab of the Lytics UI you can see how the raw data from the lytics_content_enrich stream is parsed.

2. Set up an inline recommendation

To add inline content recommendations to your website all we have to do is draft some simple HTML. Pathfora will look for appropriately named data attributes, and replace the contents of these elements with recommendations from our APIs.

First lets look at a simple, quick example, then we'll break down what these attributes mean:

<div data-pfblock="froyo_1" data-pfrecommend="froyo_content">
  <img data-pftype="image" alt="frozen yogurt recommendation">
  <h2 data-pftype="title"></h2>
  <p data-pftype="description"></p>
  <p><a data-pftype="url">Read More...</a>
</div>

Here's a quick rundown of the relevant data attributes:

image data-pftype attributes will set the src value if applied to an img element (as with the example above) or if used on a div or some other type of element it will set the background-image to be the primary image from the document.

Similarly, the url data-pftype attribute will set the href value to the url of the document if applied to an a tag, but otheriwse will set the innerHTML of the element.

Multiple Recommendations

You may have seen a section on blogs "If you liked this, you may also like..." with a list of three or more related articles. This is a common use case for content recommendations. We repeat the same HTML pattern to create multiple recommendations in a set, just remember to change the data-pfblock value. If we have multiple recommendations using the same content collection then we will ensure that the same piece of content is not shown twice on one page.

Here's a more in depth example, with a little CSS this can be easily styled to match your website:

<h1>Recommended Content</h1>

<!-- Recommendation 1 of 2 -->
<div class="rec-block" data-pfblock="froyo_1" data-pfrecommend="froyo_content">
  <div class="rec-img" data-pftype="image"></div>
  <h2 data-pftype="title"></h2>
  <p class="rec-info">by <span data-pftype="author"></span> on <span data-pftype="published"></span></p>
  <p data-pftype="description"></p>
  <p><a data-pftype="url">Read More...</a>
</div>

<!-- Recommendation 2 of 2 -->
<div class="rec-block" data-pfblock="froyo_2" data-pfrecommend="froyo_content">
  <div class="rec-img" data-pftype="image"></div>
  <h2 data-pftype="title"></h2>
  <p class="rec-info">by <span data-pftype="author"></span> on <span data-pftype="published"></span></p>
  <p data-pftype="description"></p>
  <p><a data-pftype="url">Read More...</a>
</div>

Additional Notes

• Our SDK may take a second to set the proper hide/show settings for inline elements. If you experience a "flicker" where elements are being rapidly shown then hidden and shown again you can add the following CSS line to your website to prevent this:

[data-pftrigger], [data-pfrecommend] { display: none; }

This exact CSS gets loaded by Pathfora, but adding it to your CSS ensures that elements are hidden as the document is loaded.

• Since this is primarily a developer use case we don't provide any native reporting of inline recommendations at the moment, however it is super simple to link this up to send interaction data to Lytics or Google Analytics. Check out our Lytics Javascript Tag documentation for more.

• If you'd like a "pre-baked" version of inline recommendations, we also have a version that's built from our personalize modules. You can find the documentation for this here.