Manual: How to Embed Product Stories 2.0 Into Your Website?

A product story 2.0 is a below-the-fold content page with a custom layout of multimedia and messaging assets that give the best product experience to an online shopper. In addition, Product Story 2.0 enables the seamless insert of a full version of the story and the seamless insert of individual content blocks without using frames or iframes like in Product Story 1.0. In other words, you can embed the code (HTML/CSS/JS) on your page with your own fonts and styles, switching off some of the blocks if you don’t want them. Hence customization becomes possible.

For Product Stories, a 2.0 unique lightweight pet framework has been created, including all the necessary plugins. The init script has a size of 5.4kb (gzip). It analyzes blocks used for a particular story page and pulls only the necessary .CSS and JS, which eventually reduces the overall size of the story. Again it’s a significant advantage for SEO. Additionally, the product story 2.0 code will not crash the customer’s site since now we use our own CSS and JS scripts instead of commonly used ones.

Explore some of the benefits of the Icecat Product Story 2.0 solution:

• Embed Product Stories 2.0 with a few lines of code,
• Improved performance and loading speed of Product stories 2.0,
• Advanced customization: applying custom fonts and styles, switching off/on extra modules,
• Lazy load option for media to improve SEO on product pages,
• Product stories 2.0 have a responsive design,
• Icecat hosts Product Stories 2.0, and it’s multimedia assets.

Quick Start

The simplest way to embed a product story — place a <live-story> element in your HTML:

<live-story
  data-username="openicecat-live"
  data-lang="en"
  data-brand="LG"
  data-product-code="GBB92MCBAP">
</live-story>
<script type="module" src="https://static.icecat.studio/live-story/live-story.esm.js"></script>

The element fetches and renders the story automatically. No extra JavaScript required.

For browsers without ES module support, use the classic script:

<script src="https://static.icecat.studio/live-story/live-story.js"></script>

Parameter Reference

Attribute	Required	Description
data-username	Yes	Icecat account username
data-lang	Yes	Content language (en, fr, de, etc.)
data-gtin	No	EAN, UPC, or JAN code
data-brand	No	Product brand name (used with data-product-code)
data-product-code	No	Original product code, MPN, or SKU (used with data-brand)
data-icecat-product-id	No	Icecat’s internal numerical identifier
data-version	No	Force story version: "1" or "2"*

Product identification — provide one of:

• data-gtin
• data-icecat-product-id
• data-brand + data-product-code

*Note: In most cases, you do not need to set data-version. This attribute is intended for advanced/custom integrations only. Please use it only after prior consultation with an Icecat specialist.

Identifier Fallback Logic

While you can provide a single method for product identification, the <live-story> element also supports using multiple identifiers in a single request to create a fallback mechanism.

If you provide data-brand, data-product-code, and data-gtin simultaneously, the system uses the following validation priority:

1. First, it attempts to validate and match the product based on the Brand + MPN (data-brand + data-product-code).
2. If there is no match for the Brand and MPN combination, it will automatically fall back to searching by the GTIN (data-gtin).

Example:

<live-story
  data-username="openicecat-live"
  data-lang="en"
  data-brand="LG"
  data-product-code="GBB92MCBAP"
  data-gtin="8806091079190">
</live-story>
<script type="module" src="https://static.icecat.studio/live-story/live-story.esm.js"></script>

JavaScript API

Check story availability in icecat database — hasStory()

Create the element, check availability, then insert into the DOM:

const el = document.createElement('live-story')
el.dataset.username = 'openicecat-live'
el.dataset.lang = 'en'
el.dataset.gtin = '8806091079190'const exists = await el.hasStory()

if (exists) {
  document.querySelector('#product-story').appendChild(el)
}

hasStory() makes an API call and returns true / false without rendering. The story renders only when the element is appended to the DOM.

mount() helper

Creates and appends a <live-story> element in one call. Available as a named export from the ESM build:

<script type="module">
  import { mount } from 'https://static.icecat.studio/live-story/live-story.esm.js'

  mount('#product-story', {
    username: 'openicecat-live',
    lang: 'en',
    gtin: '8806091079190',
  })
</script>

Accepts a CSS selector or an HTMLElement as the first argument. Throws if the container is not found.

liveStoryReady event

Fired on window once the script is loaded. Useful when loading the script with async or defer:

<script>
  window.addEventListener('liveStoryReady', function () {
    const story = new LiveStory({ username: 'openicecat-live', lang: 'en', gtin: '8806091079190' })
    story.exist().then(function (exists) {
      if (exists) story.insert('#product-story')
    })
  })
</script>
<script src="https://static.icecat.studio/live-story/live-story.js" defer></script>

Caching

API responses are cached in memory for 5 minutes. Multiple elements with the same options result in a single network request.

Error handling

If the API returns an error or the product has no story, the <live-story> element remains empty — no visual artifacts, no console noise for end users.

Custom Styling

Apply custom fonts and colors using CSS variables:

<style>
  body {
    --pet-font-family: 'Roboto', Arial, Helvetica, sans-serif;
    --pet-font-size: 13px;
    --pet-font-weight: 500;
    --pet-color: #000000;
    --pet-theme-color: #475be9;
    --pet-headding-font-family: 'Georgia', serif;
  }
</style><live-story
  data-username="openicecat-live"
  data-lang="en"
  data-gtin="8806091079190">
</live-story>
<script type="module" src="https://static.icecat.studio/live-story/live-story.esm.js"></script>

Style Variables

CSS Variable	Default	Description
--pet-font-family	System fonts	Primary font
--pet-font-size	16px	Text size
--pet-font-weight	400	Text weight
--pet-line-height	1.4	Line spacing
--pet-color	#212529	Text color
--pet-background	#FFFFFF	Story background
--pet-theme-color	#939393	Accent elements
--pet-headding-font-family	Inherits from --pet-font-family	All headings font
--pet-h1-font-family	Inherits from --pet-headding-font-family	H1 font
--pet-h2-font-family	Inherits from --pet-headding-font-family	H2 font
--pet-h3-font-family	Inherits from --pet-headding-font-family	H3 font
--pet-h4-font-family	Inherits from --pet-headding-font-family	H4 font
--pet-h5-font-family	Inherits from --pet-headding-font-family	H5 font
--pet-h6-font-family	Inherits from --pet-headding-font-family	H6 font

Module Toggling

Enable or disable optional modules (reviews, user-generated content). Set window.petOptions before the script loads:

<script>
  window.petOptions = {
    modules: {
      ugc: true,
      reviews: true
    }
  }
</script>
<live-story
  data-username="openicecat-live"
  data-lang="en"
  data-gtin="8806091079190">
</live-story>
<script type="module" src="https://static.icecat.studio/live-story/live-story.esm.js"></script>

Module	Default	Description
reviews	false	Testseek reviews
ugc	false	User-generated content

Version Fallback

Story version 2.0 takes priority. If unavailable, the system falls back to version 1.0 automatically.

To force a specific version, use data-version:

<live-story
  data-username="openicecat-live"
  data-lang="en"
  data-gtin="8806091079190"
  data-version="1">
</live-story>

Value	Description
(omitted)	Auto-detect (v2 preferred, v1 fallback)
"1"	Force version 1.0 (iframe-based)
"2"	Force version 2.0

Multiple Products on One Page

Each element is independent. Place as many as needed:

<live-story data-username="openicecat-live" data-lang="en" data-gtin="8806091079190"></live-story>
<live-story data-username="openicecat-live" data-lang="en" data-brand="LG" data-product-code="GBB92MCBAP"></live-story>

Identical requests are deduplicated automatically.

Migration from live-current-2.js

If you are using the legacy IcecatLive.getDatasheet() API, here is how to migrate:

Before:

<div id="container1"></div><script>
  window.addEventListener('liveload', function () {
    IcecatLive.getDatasheet({
      productstory: '#container1'
    }, {
      GTIN: '8806091079190',
      UserName: 'openicecat-live'
    }, 'en')
  })
</script>
<script src="https://live.icecat.biz/js/live-current-2.js"></script>

After:

<live-story
  data-username="openicecat-live"
  data-lang="en"
  data-gtin="8806091079190">
</live-story>
<script type="module" src="https://static.icecat.studio/live-story/live-story.esm.js"></script>

Parameter mapping

Legacy	New
UserName	data-username
Brand	data-brand
PartCode	data-product-code
GTIN	data-gtin
IcecatProductId	data-icecat-product-id
productStoryVersion: 'v1'	data-version="1"
productStoryVersion: 'v2'	data-version="2"
liveload event	liveStoryReady event

Trusted Domains / Allowlist Requirement

If the retailer has restrictions on loading third-party scripts, please ensure that https://*.icecat.studio and https://*.icecat.biz is added to the list of trusted or allowlisted domains. This is required to allow Product Stories scripts and assets to load correctly.

Legacy method: How to Embed Product Stories via Icecat Live

You can integrate Product Story as one of the Icecat Live containers using the Icecat Live Granular Call method. This method delivers content to your web page in real-time. Furthermore, it will only require a couple of lines of Javascript code in your HTML template.

You can request Product Story 2.0 using three types of product identifiers:

• Firstly, via Brand + Part code (SKU, MPN)
• Secondly, via GTIN (EAN, UPC)
• Thirdly, via the Icecat ID (the unique identifier of a product in Icecat DB)

See examples of all three Product Story request codes below:

Brand + SKU (Part code) method:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        Brand: 'LG',
        PartCode: 'GBB92MCBAP',
        UserName: 'openicecat-live'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

GTIN (EAN/UPC/JAN) method:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        GTIN: '8806091079190',
        UserName: 'openicecat-live'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

Icecat ID method:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        IcecatProductId: '87053244',
        UserName: 'openicecat-live'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

Note:
The Icecat Live script contains the async attribute in all examples in this article. This is a recommended best practice to ensure the script loads in parallel and does not affect the product page rendering, helping maintain optimal page performance and stability.

Value	Definition
UserName	Icecat User Name
Brand	The brand name of the product
PartCode	The original product code, MPN(manufacturer part number), SKU (Stock Keeping Unit)
GTIN	The GTIN: EAN (European Article Number ), UPC (Universal Product Code), or JAN (Japan Article Number)
IcecatProductId	Icecat’s Internal numerical product identifier. Only to be used by advanced users that (already) make use of the Icecat index files.

How to apply custom styles?

To apply custom style guides, simply add respective settings:

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
  <style>
    body {
      --pet-font-family: 'Roboto', Arial, Helvetica, sans-serif;
      --pet-font-size: 13px;
      --pet-font-weight: 500;
      --pet-color: #000000;
      --pet-theme-color: #475be9;
      --pet-headding-font-family: 'Georgia', serif;
      --pet-h1-font-family: 'Georgia', serif;
      --pet-h2-font-family: 'Trebuchet MS', sans-serif;
      --pet-h3-font-family: 'Arial Black', Gadget, sans-serif;
      --pet-h4-font-family: 'Tahoma', Geneva, sans-serif;
      --pet-h5-font-family: 'Verdana', Geneva, sans-serif;
      --pet-h6-font-family: 'Courier New', Courier, monospace; 
    }
  </style>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        Brand: 'LG',
        PartCode: 'GBB92MCBAP',
        UserName: 'openicecat-live'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

Value	Default settings	Definition
–pet-font-family	-apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Ubuntu, roboto, noto, arial, sans-serif	Font family. Default fonts from different operating systems
–pet-font-size	16px	Font size
–pet-font-weight	400	Font weight
–pet-line-height	1.4	Line spacing
–pet-color	#212529	Text Color
–pet-background	#FFFFFF	Story background color
–pet-theme-color	#939393	Color of bullets/arrows/other elements
–pet-headding-font-family	Inherits “–pet-font-family” if not set	Default font for all heading levels if specific h1–h6 fonts are not set
--pet-h1-font-family (h1-h6)	Inherits from “–pet-headding-font-family” if available; otherwise, inherits from “–pet-font-family”	Font families used for headings <h1> to <h6>. Each heading level can have its own specific font style.

How to switch on/off modules of Product Story 2.0?

There is a possibility to switch on/off additional modules in product stories (if they are available). By default, they are switched on. To activate them, change respective settings with “true” values.

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
<script>
    window.petOptions = {
      modules: {
        ugc: true,
        reviews: true
      }
    }
  </script>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        Brand: 'LG',
        PartCode: 'GBB92MCBAP',
        UserName: 'openicecat-live'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

Value	Default settings	Definition
reviews	false	Testseek reviews
UGC	false	User-generated content

The backup logic

Product story version 2.0 will have priority over version 1.0. The backup logic while doing granular calls is the following:

Firstly, by default, the system will send product story version 2.0. If it’s not available, product story version 1.0 will be used instead.

Secondly, by specifying the product story version keys (v1 or v2), a partner can use a particular story version:

• productStoryVersion: v1 – returns ProductStory v1.0 only
• productStoryVersion=v2 – returns ProductStory v2.0 only

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Product story example</title>
</head>
<body>
  <div id="container1"></div>
  <script>
    window.addEventListener('liveload', function () {
      IcecatLive.getDatasheet({
        productstory: '#container1'
      }, {
        Brand: 'LG',
        PartCode: 'GBB92MCBAP',
        UserName: 'openicecat-live',
        productStoryVersion: 'v1'
      }, 'en')
    })
  </script>
  <script src="https://live.icecat.biz/js/live-current-2.js"></script>
</body>
</html>

Value	Default settings	Definition
productStoryVersion	–	Can have either “v1” or “v2”

Alternative outputs (XML and JSON)

XML/JSON: we publish .txt files with HTML product story 2.0 code:

Please, contact us in case of questions or comments via your Icecat account manager or contact us via the website.