{"_id":"57e16e23632fd4220007a63a","parentDoc":null,"user":"5668fa9755e4b32100935d41","category":{"_id":"56a17776470ae00d00c30642","version":"5668fab608f90021008e8832","__v":5,"project":"5668fab608f90021008e882f","pages":["56a1827ad847b50d00a27729","56a1831f44f3d80d00a2c3c9","56a18a6244f3d80d00a2c3d3","56a18a83932d7c0d008bf231","56a18d1bd847b50d00a27735"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-22T00:27:34.102Z","from_sync":false,"order":5,"slug":"inventory","title":"Inventory (JavaScript)"},"githubsync":"","project":"5668fab608f90021008e882f","version":{"_id":"5668fab608f90021008e8832","__v":19,"project":"5668fab608f90021008e882f","createdAt":"2015-12-10T04:08:22.769Z","releaseDate":"2015-12-10T04:08:22.769Z","categories":["5668fab708f90021008e8833","569740f124490c3700170a64","569742b58560a60d00e2c25d","569742bd0b09a41900b2446c","569742cd69393517000c82b3","569742f459a6692d003fad8f","569743020b09a41900b2446d","5697430b69393517000c82b5","56a17776470ae00d00c30642","56a2c48a831e2a0d0069b1ad","56b535757bccae0d00e9a1cd","56e1ff6aa49fdc0e005746b5","57e1c88115bf6522002a5e4e","57fa65275ba65a17008b988f","57fbeea34002550e004c032e","58474584889b6c2d00fb86e9","58475dcc64157f0f002f1907","587e7b5158666c2700965d4e","58a349fc30852819007ba083"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.18.0","version":"1.18"},"__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-20T17:13:07.136Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"About content identifier\",\n  \"body\": \"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).\\n\\nAlso we DON'T accept numerical value for a content identifier. It must be a `string`\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Title and tag field\",\n  \"body\": \"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.\"\n}\n[/block]\nFor 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:\n<ul>\n<li>You want us to return the fields in recommendations so you can render them.</li>\n<li>You want to set rules associated with the values of those fields.</li>\n<li>You expect that access to those fields will help us train our model better.</li>\n</ul>\nTo send us fields, you need to include them in the source HTML of your pages. There are two ways you can do this:\n<ul>\n<li>Open Graph tags: The advantage is that you might have set these up already, so it’s less work to integrate us.</li>\n<li>Custom LiftIgniter JSON object: This allows you to pass in new fields and overwrite the values found in Open Graph tags.</li>\n</ul>\n**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.\n\nAlthough we scrape all these fields, we do not return fields beyond our standard list unless you specifically [request those fields](https://liftigniter.readme.io/docs/psetrequestfields-field_array) in your query.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Open Graph tags\"\n}\n[/block]\nFor 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](http://ogp.me/).\n\nFor 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<meta property=\\\"og:title\\\" content=\\\"sample-title\\\"/>\\n<meta property=\\\"og:url\\\" content=\\\"http://xyz.com/sample-url\\\"/>\\n<meta property=\\\"article:author\\\" content=\\\"http://xyz.com/sample-author\\\"/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nIf that item is returned as a recommendation, the JSON object corresponding to this item will contain this title field with value sample-title:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"url\\\": \\\"http://xyz.com/sample-url\\\",\\n  \\\"title\\\": \\\"sample-title\\\",\\n  \\\"author\\\": \\\"http://xyz.com/sample-author\\\"\\n  ...\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Open Graph profile\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"LiftIgniter JSON object\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Defining liftigniter-metadata JSON\",\n  \"body\": \"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.\"\n}\n[/block]\nThere are a couple of reasons you might want to use our custom LiftIgniter JSON object to pass in fields.\n<ul>\n<li>You have fields you want us to use that don’t fit into the standard Open Graph framework.</li>\n<li>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.</li>\n</ul>\nWhen 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.\n\nHere is an example LiftIgniter JSON object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script id=\\\"liftigniter-metadata\\\" type=\\\"application/json\\\">\\n{\\n    \\\"reviewCount\\\": 158,\\n    \\\"rating\\\" : 4.2\\n}\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe `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.\n\nHere’s a worked-out example where you have some fields in the JSON object and some as Open Graph fields:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script id=\\\"liftigniter-metadata\\\" type=\\\"application/json\\\">\\n{\\n    \\\"title\\\" : \\\"5 Cool Ways to Eat an Apple\\\",\\n    \\\"tags\\\" : [\\\"apple\\\", \\\"cool\\\", \\\"nutrition\\\"]\\n}\\n</script>\\n<meta property=\\\"og:title\\\" content=\\\"These 5 Cool Ways to Eat An Apple Left Me Salivating. You'd NEVER Think of #3.\\\"/>\\n<meta property=\\\"og:url\\\" content=\\\"http://viral-website.com/eating-apples/\\\">\\n<meta property=\\\"og:description\\\" content=\\\"Boy, was I wrong to think I knew how to eat an apple!\\\"/>\\n<meta property=\\\"og:image\\\" content=\\\"http://cdn.viral-website.com/winking-apple.jpg\\\"/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Note on arrays\"\n}\n[/block]\nIn 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<meta property=\\\"article:tag\\\" content=\\\"women\\\"/>\\n<meta property=\\\"article:tag\\\" content=\\\"feminism\\\"/>\\n<meta property=\\\"article:tag\\\" content=\\\"politics\\\"/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe 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.\n\nHowever, 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script id=\\\"liftigniter-metadata\\\" type=\\\"application/json\\\">\\n{\\n  ...\\n  \\\"tag\\\" : [\\\"men\\\", \\\"women\\\"],\\n  ...\\n}\\n</script>\\n<meta property=\\\"article:tag\\\" content=\\\"women\\\"/>\\n<meta property=\\\"article:tag\\\" content=\\\"feminism\\\"/>\\n<meta property=\\\"article:tag\\\" content=\\\"politics\\\"/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nthen the array of tags inside the JSON tages precedence, and we store the value of \"tag\" as the array [\"men\", \"women\"].\n\nNote that it’s important that you use the correct format for array of strings, rather than just a single comma-separated value string.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"tag\\\" : \\\"men,women\\\" // This is interpreted as a single tag with value \\\"men,women\\\" rather than as two tags.\\n\\\"tag\\\" : [\\\"men\\\", \\\"women\\\"] // This is interpreted as an array of two tags, as was the likely original intention\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nFurther, if you specify an empty array in the LiftIgniter JSON object, that will also overwrite the array as defined by OG tags outside.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fields with timestamps\"\n}\n[/block]\nYou 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.\n\nAll timestamp fields must be passed in the DateTime ISO 8601 format as described in the Open Graph Protocol website.\n\nNote that we require the field names to contain a timezone.\n\nHere are some example formats that we correctly parse.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Format\",\n    \"h-1\": \"Example\",\n    \"0-0\": \"yyyy-MM-dd'T'HH:mm:ssZ\",\n    \"0-1\": \"2017-01-21T09:56:36-08:00\",\n    \"1-0\": \"yyyy-MM-dd HH:mm:ssZ\",\n    \"1-1\": \"2017-01-21 09:56:36-08:00\",\n    \"2-0\": \"yyyy-MM-dd'T'HH:mm:ss.SSSZ\",\n    \"2-1\": \"2017-01-21T09:56:36.321-08:00\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nThe fields are:\n\n* `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`.\n* `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`.\n* `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`.\n\nWe will automatically stop showing articles after the expiration time as found the last time it was scraped.\n[block:api-header]\n{\n  \"title\": \"Note on devices (desktop versus mobile)\"\n}\n[/block]\nKeep 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\")](doc:pinit) documentation.","excerpt":"","slug":"defining-your-inventory","type":"basic","title":"Defining your Inventory"}

Defining your Inventory


[block:callout] { "type": "warning", "title": "About content identifier", "body": "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).\n\nAlso we DON'T accept numerical value for a content identifier. It must be a `string`" } [/block] [block:callout] { "type": "info", "title": "Title and tag field", "body": "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." } [/block] 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: <ul> <li>You want us to return the fields in recommendations so you can render them.</li> <li>You want to set rules associated with the values of those fields.</li> <li>You expect that access to those fields will help us train our model better.</li> </ul> To send us fields, you need to include them in the source HTML of your pages. There are two ways you can do this: <ul> <li>Open Graph tags: The advantage is that you might have set these up already, so it’s less work to integrate us.</li> <li>Custom LiftIgniter JSON object: This allows you to pass in new fields and overwrite the values found in Open Graph tags.</li> </ul> **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](https://liftigniter.readme.io/docs/psetrequestfields-field_array) in your query. [block:api-header] { "type": "basic", "title": "Open Graph tags" } [/block] 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](http://ogp.me/). 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: [block:code] { "codes": [ { "code": "<meta property=\"og:title\" content=\"sample-title\"/>\n<meta property=\"og:url\" content=\"http://xyz.com/sample-url\"/>\n<meta property=\"article:author\" content=\"http://xyz.com/sample-author\"/>", "language": "html" } ] } [/block] If that item is returned as a recommendation, the JSON object corresponding to this item will contain this title field with value sample-title: [block:code] { "codes": [ { "code": "{\n \"url\": \"http://xyz.com/sample-url\",\n \"title\": \"sample-title\",\n \"author\": \"http://xyz.com/sample-author\"\n ...\n}", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Open Graph profile", "body": "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." } [/block] [block:api-header] { "type": "basic", "title": "LiftIgniter JSON object" } [/block] [block:callout] { "type": "info", "title": "Defining liftigniter-metadata JSON", "body": "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." } [/block] There are a couple of reasons you might want to use our custom LiftIgniter JSON object to pass in fields. <ul> <li>You have fields you want us to use that don’t fit into the standard Open Graph framework.</li> <li>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.</li> </ul> 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: [block:code] { "codes": [ { "code": "<script id=\"liftigniter-metadata\" type=\"application/json\">\n{\n \"reviewCount\": 158,\n \"rating\" : 4.2\n}\n</script>", "language": "html" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<script id=\"liftigniter-metadata\" type=\"application/json\">\n{\n \"title\" : \"5 Cool Ways to Eat an Apple\",\n \"tags\" : [\"apple\", \"cool\", \"nutrition\"]\n}\n</script>\n<meta property=\"og:title\" content=\"These 5 Cool Ways to Eat An Apple Left Me Salivating. You'd NEVER Think of #3.\"/>\n<meta property=\"og:url\" content=\"http://viral-website.com/eating-apples/\">\n<meta property=\"og:description\" content=\"Boy, was I wrong to think I knew how to eat an apple!\"/>\n<meta property=\"og:image\" content=\"http://cdn.viral-website.com/winking-apple.jpg\"/>", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Note on arrays" } [/block] 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: [block:code] { "codes": [ { "code": "<meta property=\"article:tag\" content=\"women\"/>\n<meta property=\"article:tag\" content=\"feminism\"/>\n<meta property=\"article:tag\" content=\"politics\"/>", "language": "html" } ] } [/block] 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: [block:code] { "codes": [ { "code": "<script id=\"liftigniter-metadata\" type=\"application/json\">\n{\n ...\n \"tag\" : [\"men\", \"women\"],\n ...\n}\n</script>\n<meta property=\"article:tag\" content=\"women\"/>\n<meta property=\"article:tag\" content=\"feminism\"/>\n<meta property=\"article:tag\" content=\"politics\"/>", "language": "html" } ] } [/block] 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. [block:code] { "codes": [ { "code": "\"tag\" : \"men,women\" // This is interpreted as a single tag with value \"men,women\" rather than as two tags.\n\"tag\" : [\"men\", \"women\"] // This is interpreted as an array of two tags, as was the likely original intention", "language": "javascript" } ] } [/block] Further, if you specify an empty array in the LiftIgniter JSON object, that will also overwrite the array as defined by OG tags outside. [block:api-header] { "type": "basic", "title": "Fields with timestamps" } [/block] 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. [block:parameters] { "data": { "h-0": "Format", "h-1": "Example", "0-0": "yyyy-MM-dd'T'HH:mm:ssZ", "0-1": "2017-01-21T09:56:36-08:00", "1-0": "yyyy-MM-dd HH:mm:ssZ", "1-1": "2017-01-21 09:56:36-08:00", "2-0": "yyyy-MM-dd'T'HH:mm:ss.SSSZ", "2-1": "2017-01-21T09:56:36.321-08:00" }, "cols": 2, "rows": 3 } [/block] 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. [block:api-header] { "title": "Note on devices (desktop versus mobile)" } [/block] 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")](doc:pinit) documentation.