Defining your Inventory

🚧

About content identifier

For JS SDK integration, we recommend you to name your content identifier as url since that's the basic key field name that our backend accepts. An alternative is to call it an id, but you'll have to ask us to change the key field name (at least for now).

Also we DON'T accept numerical value for a content identifier. It must be a string

📘

Title and tag field

Aside from calling the identifier url, we also recommend you to use field name title for content title. This field is referenced for comparing semantic similarity.

For each of your inventory items that we could potentially recommend, you might have a bunch of fields, such as title, description, subtitle, author, tags. There are three reasons you might want to make these fields available to us:

• You want us to return the fields in recommendations so you can render them.
• You want to set rules associated with the values of those fields.
• You expect that access to those fields will help us train our model better.

To send us fields, you need to include them in the source HTML of your pages. There are two ways you can do this:

• Open Graph tags: The advantage is that you might have set these up already, so it’s less work to integrate us.
• Custom LiftIgniter JSON object: This allows you to pass in new fields and overwrite the values found in Open Graph tags.

**Note that these fields are fields for your `inventory items` and not fields associated with the user context.** For instance, you can use these fields to pass information on the title of your article or the price of your product. But these fields should not be used to pass information about the current user or context. To pass information about the user context, use the opts in the register call.

Although we scrape all these fields, we do not return fields beyond our standard list unless you specifically request those fields in your query.

Open Graph tags

For any page on your site, we scrape off all Open Graph tags. This includes tags that begin with og: as well as some article:, music:, video: and book: tags. You can get detailed documentation about standard OG tags at The Open Graph protocol website.

For each such tag, the field name we store is the part after the og: (or article: or other initial prefix). For instance, suppose one of your pages has the following in its HTML:

HTML

<meta property="og:title" content="sample-title"/>
<meta property="og:url" content="http://xyz.com/sample-url"/>
<meta property="article:author" content="http://xyz.com/sample-author"/>

If that item is returned as a recommendation, the JSON object corresponding to this item will contain this title field with value sample-title:

JavaScript

{
  "url": "http://xyz.com/sample-url",
  "title": "sample-title",
  "author": "http://xyz.com/sample-author"
  ...
}

📘

Open Graph profile

The Open Graph protocol supports profiles for authors, so that you can use a field like article:author to point to an author profile page, and then give more biographical information in profile tags on that author page. We do not currently support profiles. So any additional information about the author that you want us to include in results must be in the article page itself.

LiftIgniter JSON object

📘

Defining liftigniter-metadata JSON

We parse the text content of the element as a JSON. So make sure that the element's text content has the string version of the JSON by the time the DOM is ready.

There are a couple of reasons you might want to use our custom LiftIgniter JSON object to pass in fields.

• You have fields you want us to use that don’t fit into the standard Open Graph framework.
• You want to rewrite some field names. The og:title value is chosen to facilitate Facebook sharing, but our recommendation widget is a different use case. One common customer issue: `og:title` includes the page title and the site name, whereas when showing recommendations internally you don’t want to show the site name.

When we look at your page source, we give preference to the values found in our LiftIgniter JSON object over and above the Open Graph tags.

Here is an example LiftIgniter JSON object:

HTML

<script id="liftigniter-metadata" type="application/json">
{
    "reviewCount": 158,
    "rating" : 4.2
}
</script>

The script id must be liftigniter-metadata and the script type must be application/json. The fields are specified in JSON format. Each field could be a string, a number, or a sequence of strings. We do not support other data formats.

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

HTML

<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"/>

Note on arrays

In the Open graph protocol, to specify an array, you specify each field separately. For instance, suppose an article has tags women, feminism, and politics. The tags would be specified using the Open Graph protocol as follows:

HTML

<meta property="article:tag" content="women"/>
<meta property="article:tag" content="feminism"/>
<meta property="article:tag" content="politics"/>

The Open Graph protocol parses the page and picks up all three tags "women", "feminism", and "politics", forming an array from them. LiftIgniter does the same.

However, if you specify any value (either a string or an array of strings) inside the LiftIgniter JSON object, this takes precedence over the values outside. For instance, suppose you specify:

HTML

<script id="liftigniter-metadata" type="application/json">
{
  ...
  "tag" : ["men", "women"],
  ...
}
</script>
<meta property="article:tag" content="women"/>
<meta property="article:tag" content="feminism"/>
<meta property="article:tag" content="politics"/>

then the array of tags inside the JSON tages precedence, and we store the value of "tag" as the array ["men", "women"].

Note that it’s important that you use the correct format for array of strings, rather than just a single comma-separated value string.

JavaScript

"tag" : "men,women" // This is interpreted as a single tag with value "men,women" rather than as two tags.
"tag" : ["men", "women"] // This is interpreted as an array of two tags, as was the likely original intention

Further, if you specify an empty array in the LiftIgniter JSON object, that will also overwrite the array as defined by OG tags outside.

Fields with timestamps

You can pass in formatted timestamps for any fields of your choice, but we allow timestamp-specific rules only for some specific fields. For other fields we will treat the timestamps as strings.

All timestamp fields must be passed in the DateTime ISO 8601 format as described in the Open Graph Protocol website.

Note that we require the field names to contain a timezone.

Here are some example formats that we correctly parse.

Format	Example
yyyy-MM-dd'T'HH:mm:ssZ	2017-01-21T09:56:36-08:00
yyyy-MM-dd HH:mm:ssZ	2017-01-21 09:56:36-08:00
yyyy-MM-dd'T'HH:mm:ss.SSSZ	2017-01-21T09:56:36.321-08:00

The fields are:

• published_time: In the Open Graph framework, the property name is article:published_time. We will drop the article: prefix and store the field as published_time. If passing it in the custom LiftIgniter JSON object, simply call it published_time.
• modified_time: In the Open Graph framework, the property name is article:modified_time. We will drop the article: prefix and store the field as modified_time. If passing it in the custom LiftIgniter JSON object, simply call it modified_time.
• expiration_time: In the Open Graph framework, the property name is article:expiration_time. We will drop the article: prefix and store the field as expiration_time. If passing it in the custom LiftIgniter JSON object, simply call it expiration_time.

We will automatically stop showing articles after the expiration time as found the last time it was scraped.

Note on devices (desktop versus mobile)

Keep in mind that we are collecting inventory from both your desktop and mobile site, so if the same URL has different inventory metadata on desktop and mobile, then we might at any given point in time have metadata for either the desktop or the mobile site. Therefore, you should make sure either than your inventory metadata for the same url is consistent across desktop and mobile, or disable inventory collection on the device where the metadata is inaccurate. For instance, of mobile inventory metadata is inaccurate or incomplete, you can disable inventory collection specifically on mobile by setting inventory.collect = false as described in our $p("init") documentation.