Examples and Exceptions

Example

Here’s a worked-out example where you have some fields in the JSON object and some as Open Graph fields:

<script id="liftigniter-metadata" type="application/json">
{
    "title" : "5 Cool Ways to Eat an Apple",
    "tags" : ["apple", "cool", "nutrition"]
}
</script>
<meta property="og:title" content="These 5 Cool Ways to Eat An Apple Left Me Salivating. You'd NEVER Think of #3."/>
<meta property="og:url" content="http://viral-website.com/eating-apples/">
<meta property="og:description" content="Boy, was I wrong to think I knew how to eat an apple!"/>
<meta property="og:image" content="http://cdn.viral-website.com/winking-apple.jpg"/>

Now suppose you request all these fields when requesting our recommendations:

$p("setRequestFields", ["url","title","tags","image","thumbnail","description","subtitle"]);
$p("fetch");

The JSON object for this item will be as follows:

{
  "url" : "http://viral-website.com/eating-apples/",
  "title" : "5 Cool Ways to Eat an Apple",
  "tags" : ["apple", "cool", "nutrition"],
  "image" : "http://cdn.viral-website.com/winking-apple.jpg",
  "thumbnail" : "http://cdn.viral-website.com/winking-apple.jpg",
  "description" : "Boy, was I wrong to think I knew how to eat an apple!"
}

Note that the title field in the LiftIgniter JSON object overwrites the og:title. The subtitle field is not returned because we didn’t have a value for that field.

Special fields: title, url and thumbnail

For the title field, we use the following order of precedence:

  • `title` as specified in the LiftIgniter JSON object in the page HTML.
  • `og:title` in the page HTML.
  • The current title of the page.

📘

Notes on displaying site name

We have noticed that some customers include the site name in their page title, but may not want to display the site name when showing the page in a recommendation widget. You can either send us the correct title in the JSON object or do a transformation at your end after receiving the title to remove the site name.

For the url field, we use the following order of precedence to determine the correct URL:

  • `url` as specified in the LiftIgniter JSON object in the page HTML.
  • The href field for link rel=`canonical` in the page source.
  • `og:url` in the page HTML.
  • The current URL of the page, after stripping out all tags (anything after a `?` symbol) and everything after a hash symbol.

It’s particularly important that you specify canonical URLs so as to avoid us returning recommendations that duplicate each other or duplicate the user’s recent browsing history.

📘

Matching subdomain

We have noticed that a number of websites that engage in social sharing use separate subdomains for social sharing that redirect to the same articles. Please make sure that the canonical URL you specify is the same for all the versions of the page, including the ones shared on social media. Otherwise, we might have trouble identifying pages correctly.

For the thumbnail field, we return a copy of the image field (for which we check the LiftIgniter JSON object first and then check the og:image tag) unless you have specified a thumbnail field in the custom LiftIgniter JSON object.

Global rules

We currently support some simple rules surrounding what items we return in recommendations. These rules need to be activated manually by the LiftIgniter team and may take a few days to activate. We intend to eventually offer support for a more flexible rule system. This section will be updated when we update our rule system.

The rules we currently support are:

  • Global exclusion: Always exclude items satisfying some condition (such as a particular tag, or a numerical score above or below some threshold) from recommendations.
  • Exclusions based on optional parameters: Based on some optional parameters you pass in in your SDK query, we can exclude items satisfying a particular condition.
  • Global boost: We can boost content satisfying conditions (such as a tag or a title term). However, the way we currently implement boosts does not offer any guarantee of how much more often the boosted content will show up.
  • Boost based on optional parameters: These are boosts that are activated only if you pass in optional parameters.

We have one global exclusion rule activated by default. If you include a field called "noShow" with value "true" in the LiftIgniter JSON object, then the item will be included in our inventory but will never be returned in recommendations.

<script id="liftigniter-metadata" type="application/json">
{
  ...
  "noShow" : "true",
  ...
}
</script>

For other global exclusion rules, please get in touch with the LiftIgniter team. It can take us up to one week to activate your rule framework.

Note that pages where you mark "noIndex" as "true" won’t enter our inventory at all and will never be recommended. However, for low-quality items, we recommend using noShow instead of noIndex. That’s because having an item in the inventory, even if we never show it, allows us to show better recommendations if the user is currently on, or has recently visited, such a page.

Forbid us from indexing some items

🚧

noShow is recommended

We do support this feature, but using noShow instead of noIndex is better in most cases.

When we start working with you, we determine the type of site you have and the area where you want to show recommendations, and configure our system to pick up the right types of inventory items.

In some cases, there might be items that look like inventory items, but that you don’t actually want us to treat as inventory items. Examples are:

  • Site contact pages or other site information pages.
  • Temporary article pages created for experimentation such as A/B testing titles.
For such pages, add a field `noIndex` with value `true` in the custom LiftIgniter JSON object:
<script id="liftigniter-metadata" type="application/json">
{
  ...
  "noIndex" : "true",
  ...
}
</script>

We do not recommend the use of noIndex for cases where you want us to avoid showing low-quality items that are legitimately in the inventory.

Note that it may take us up to 24 hours to drop an item from the inventory after a "noIndex" tag is applied.