NAV Navbar
Product Hero API

Shop owners are able to fully manage Product Hero Banners on their shop, feed them with data, but also comply designs with their corporate branding with our Carousel JS API (JS).

Also B2B businesses can create new organizations, sites and carousels for their customers with our Client Management API.

Basics

Client Hierarchy

Organization

Organization represents a partner, practically a webshop. Every organization can have a Product Feed URL that will be crawled regularly (per day, or see schedule settings). All the data will pre-processed and analyzed for exposing the best possible product content and imagery. CDNKey is the unique indentifier in an organization.

Property Description
cdnKey (unique, read only) A token represents the given client
name Readable name
productFeedUrl URL of the product feed
productFeedSchedule A CRON expression like scheduling of the regular product feed processing.
productFeedOptions Settings for the feed processor on how it should handle the product feed itself, the entries in it, etc. See Product Feed Options

Site

A site is basically represents a placement on a website, that is, a box on a webshop (e.g. main page hero carousel, bottom carousel on a product page). Every organization can have one or more sites. The sites have predefined design settings (color schemes, fonts, paddings, etc). Site Key is the unique identifier of a site.

Property Description
siteKey (unique, read only) A token represents the given placement
name Readable name
url (unique) URL where the banner can be reached. In some cases is not one exact location (e.g. product page bottom carousel), but still mandatory for checking / testing purposes
container A DOM query selector that carousel.js is searching for as target. As the target element is found, carousel.js starts drawing the banner in it.
containerWidth Intended width of the container
containerHeight Intended height of the container
bannerWidth Initial width of the banner
bannerHeight Initial height of the banner
mobileBannerWidth (optional) Initial width of the carousel on mobile devices
mobileBannerHeight (optional) Initial height of the carousel on mobile devices
merchantType (optional) Recommender type of the shop, if any
merchantId (optional) Recommender identifier of the shop, if any. This lets the carousel to ask for product recommendation according to the given placement.
designParameters Design parameters for the site. See Design Parameters

Hero

Hero is an actual carousel variant for a site. Every site can have one live Hero and multiple previous, inactive heroes. Hero contains the carousel slides.

Property Description
name Readable name
live If this hero is the live hero for the site or an inactive one.

Designing and Drawing Concepts

Designing Parameters

The brand specific design settings is defined in a JSON file. Desing Parameters file consists of color schemes, font types, padding sizes, animation settings that force the drawer to process banners that apply this the webshop design guidelines. To learn more see Design Parameters

Draw

This is the mechanism that decides what the required componenst for a just requested banner are, collects these components and optimizes the position, size and coloring of them to let the final result meet a bunch of criteria that makes a good creative: nice and large images, avoiding empty spaces and overlaps, perfectly balanced font sizing for the given text and the available space for it. This sophisticated method runs in the cloud, the client receives only the necessary, easy-to-display data package that lets the Player to draw the banner quickly, without “thinking” over all the priorities.

Player

The part of the carousel.js that acually draws the banner represented in Build Data in the HTML DOM. It does minimal to no further processing on this bundle, as all the necessary decisions and calculations were made previously by the Draw mechanism.

The following elements can be created and placed by the Draw mechanism:

Name Description
Image Photo of the product (optionally with repeated or blurred background)
Message Name of the product
Subject Category or brand information
CTA Action button
Price / Msrp Price and optionally the MSRP (non-sale) of the product. Can be attached to the CTA or placed inside the Sticker (in price tag mode)
Sticker Badge placed on the banner. It has 3 modes: off, badge (discount value, e.g. '50%') or price tag (e.g. $49 $39)
Pattern One of the patterns that were allowed in the Design Parameters
Gradient Radial gradient around the Image

Portability

All dimensions, positions, font sizes, etc. are only used to get the correct aspect ratio. The container aspect ratio is corrected on window resize event, where we can take advantage of highly optimized, GPU-enabled rendering engine of the web browser. The banners are calculated in two sizes: in the pre-defined normal banner size for desktop computers and in the mobile banner size for portable devices. By default, it is a squared version of the banner, optimized for the given device in size.

Data Handling

There are a few steps Product Hero takes to convert data from one form to another that is essential for creating banners.

Product Feed

XML product feed with the client's product data.

Product Data

Product Data originate from the client's Product Feed. Product metadata (name, product id, product page URL, etc.) is extracted by the feed processor, the product image is processed by the image preprocessor and all the derived data and image parameters are stored for further usage. So the product data consist of two main parts:

Source Data

This can be channeld into the system in two ways:

Image Metadata

Every product image is scaled to an optimized size and copied to our CDN. Images will be analyzed for transparency, shape and many more properties to let us display the best possible banner composition.

Image metadata can also be channeld into the system in two ways:

Build Data

The Draw mechanism converts Product Data to Build Data that is an easy-to-display, processor friendly data format for the Player.

dia

Carousel JS API

In order to use Product Hero's Carousel API you need to have a published, live carousel. You can do that in the Carousel Editor.

Embedding the Script

You can find embed code in the Editor by pressing Embed Code menu on the top.

carousel.js is the JavaScript file that has to be embedded into the website. The file includes all placement specific settings (carousel width, container ID, etc.) and the drawing plan data a.k.a. Build Data in case you create manual product slides in the carousel editor or upload custom slides by importing a complete carousel slide as an image. On the other hand if you use recommender placeholder slides in the editor, their data will be loaded on the fly as a user navigates to location of the carousel. Then the carousel ask the product recommender of the site for a personal product recommendation for the give user, the Build Data will be created on the fly in the cloud. Then the carousel.js displays the creative.

Embed Code

<script src="https://static.cdn.producthero.ai/<siteKey>/carousel.js" data-target-id="<targetId>"></script>

Parameters:

You can insert the JS wherever you want on your page, but it's strongly recommended to insert it before closing </head> tag. carousel.js will not block your page load because fonts, background and other additional data will be loaded asynchronously.

Controlling the Script

Once carousel.js is embedded into a page, the first slide data and the required webfonts are ready and the target DOM element is loaded, the carousel starts playing. If you want to feed the carousel with you own data or recommender please construct an object like this:

With the Carousel JS API you are able to display one or multiple slides in a carousel. It will draw well designed banners based on the given Product Data. The Draw mechanism will find an optimal composition for all the items that have to be displayed and inject the optimized HTML and CSS structure into the DOM element you defined in the call.

Communication layer

If you want to feed the carousel with your own data or data provided by your recommender system you should start by constructing an array-like communication layer object, called ProductHeroCommands:

window.ProductHeroCommands = ProductHeroCommands || []; // !!! Make sure not to overwrite existing 'ProductHeroCommands' with window.ProductHeroCommands []; !!!

Once created, the carousel can receive commands by pushing one in it:

var myProductHeroCommand = /* ... */;

ProductHeroCommands.push(myProductHeroCommand);

myProductHeroCommand: your command to the carousel, see below.

If you have multiple carousels on the current web site, you must create them with data-target-id provided to let them decide if a given command targets them. In this case you should push an array in the communication layer with your command as the first element, and the target ID string as the second:

var myProductHeroCommand = /* ... */;

ProductHeroCommands.push([myProductHeroCommand, 'targetId']);

myProductHeroCommand: your command to the carousel, see below. targetId refers to value of data-target-id attribute of the <script> tag of the embed code.

Once you push something into the array it will be processed immediately.

Command anatomy

Single commands without any parameters like destroy can be sent as their name as a string, like:

ProductHeroCommands.push('destroy');

Or with target ID if necessary:

ProductHeroCommands.push(['destroy', 'targetId']);

Commands with parameters can be sent as an object with command name as key and parameters as value, like:

ProductHeroCommands.push({
  slides: [...]
});

Or with target ID:

ProductHeroCommands.push([
  {
    slides: [...]
  },
  'targetId'
]);

Multiple commands can also be sent with multiple key-value pairs in the object. Commands with no parameters can also be sent with a true as parameter:

ProductHeroCommands.push({
  slides: [...],
  options: {...},
  stop: true
});

Inside this object also targetId can be set:

ProductHeroCommands.push({
  stop: true,
  targetId: 'targetId'
});

If targetId is set in both ways, the one inside the command takes precedence:

ProductHeroCommands.push([
  {
    stop: true,
    targetId: 'targetId-2'
  },
  'targetId-1'
]);

Here targetId-2 will be used.

Set slides

Replace slides of the carousel.

ProductHeroCommands.push({
  slides: [
    {...},
    {...},
    ...,
    {...}
  ]
});

slides: An array of new slides to replace current carousel slides with

With product from the previously processed Product Feed:

ProductHeroCommands.push({
  slides: [
    {
      sku: "123abc"
    }, {
      sku: "987zyx"
    }
  ]
});

sku: keys refer to products in the previously processed Product Feed.

Without previously processed Product Feed, you can use the on-the-fly way:

ProductHeroCommands.push({
  slides: [
    {
      sku: "aaa111",
      image: "http://example.com/product_images/aaa111.jpg",
      title: "Black Friday",
      text: "Awesome Product",
      price: 59.99,
      msrp: 99.99,
      url: "http://example.com/product_pages/aaa111.html",
      tip: "Cheapest ever!", // optional
      seed: 0 // optional, change only if you want to re-arrange the banner
    }, {
      sku: "bbb222",
      image: "http://example.com/product_images/bbb222.jpg",
      title:"Yellow Rubber Duck",
      text:"Greatest Duck",
      price: 0.99,
      msrp: 2.99,
      url: "http://example.com/product_pages/bbb222.html"
    }
  ]
});

sku: product identifier for the given product image: URL of the product image for the given product title: Title for the banner text: Text for the banner price: The current price of the given product msrp: The non-sale or MSRP price of the given product url: URL of the product page of the given product tip: An optional, tiny message about the product. seed: An optional value to draw the banner based on this value. With the same value given, the same stiled banner will be drawn.

To enable on-the-fly product data processing, please contact us at want@producthero.ai.

Settings

Override predefined settings of the carousel.

ProductHeroCommands.push({
  settings: {
    ...,
    ...
  }
});

settings: An object with keys and values to override predefined settings

ProductHeroCommands.push({
  settings: {
    delay: 7000,
    container: "#your-container-selector"
  }
});

delay: delay between carousel slidings container: DOM container for the banner. It can be started with a "#" to use it as a HTML node ID, or with a "." to use it as a HTML class selector (first matching element will be used).

Destroy

Destroy the carousel.

ProductHeroCommands.push('destroy');

Start/stop sliding

For debugging purposes you may need to stop and start carousel animation:

ProductHeroCommands.push('stop');
ProductHeroCommands.push('start');

To catch load, impression and click events you can use the followings:

document.addEventListener('productheroevent', function (e) {

  // do your regular analytics stuff, e.g.:

    if (window.dataLayer && typeof window.dataLayer.push === 'function') {
        window.dataLayer.push({
      'event': 'ProductHero',
            'event_detail': JSON.stringify(e.detail),
            'event_category': 'ProductHero On Home Page',
            'event_action': e.detail.action,
            'event_label': e.detail.url || e.detail.id,
        });
    }
}, false);

Client Management API

In order to use Client Management API you need to have administrator or group manager privileges.

Sign in

Authenticate the session to let you send other request.

  POST https://api.producthero.com/user/login

Head:

  Content-Type: application/json

Body:

{
  "email": "john@example.com",
  "password": "********",
}

Sign out

Close the session to prevent sending more requests.

HTTP Request

  POST https://api.producthero.com/user/logout

Head:

  Content-Type: application/json

Body:


Manage Organizations

The Organization is the top level of the hierarchy. Organizations can have one or more sites.

Get organization

Get information about an existing organization.

  GET https://api.producthero.com/admin/organization?cdnKey={CDN Key}

cdnKey: identification token of the given organization

Create / modifiy organization

HTTP Request

  POST https://api.producthero.com/admin/organization

Head:

  Content-Type: application/json

Body:

{
  cdnKey: "ABC123456789",
  name: "My Organization",
  productFeedUrl: "https://example.com/product-feed.xml"
}
Attribute Type Description
cdnKey OR prefix string CDN key of the organization to set or a prefix to create new. Prefix is 3-5 character alphabetic string that refers to the organization itself. Eg: for Best Buy "bebuy" is a good prefix. In this case BEBUYxxxXXX... will be the CDN key, "BEBUY" is the upper case prefix, "x" is a random lower case letter and "X" is a random alphanumeric character. Sites will inherit this prefix. Normal site names will be like BEBUY?xxxXXX..., that is almost the same as the CDN key, but has a number "?" in it that is 1 for the first site, 2 is for the second, etc. test sites will have the same formatted site keys, but the prefix will be lower case, like bebuy?xxxXXX... Sites cannot be added to an organization that does not follow this convention (ie. older, manually created ones).
name string Name of the oragnization
productFeedUrl optional string URL of product feed
productFeedSchedule optional string CRON formatted schedule to handle the product feed automatically (eg: 0 5 * * *)
productFeedOptions optional object Product feed handling options (mapping, separator character, etc.)
dryRun optional boolean If true, will not save the result, just return it

Response is like for GET request.

Delete organization

HTTP Request

  DELETE https://api.producthero.com/admin/organization?cdnKey={CDN Key}

cdnKey: identification token of the given organization to delete

Manage Sites

The Site is the second level of the hierarchy. Sites can have one or more Heroes of which at most one can be active.

Get information about an existing site.

HTTP Request

  GET https://api.producthero.com/admin/site?siteKey={Site Key}

siteKey: identification token of the given site

Create / modifiy site

HTTP Request

  POST https://api.producthero.com/admin/site

Head:

  Content-Type: application/json

Body:

{
  siteKey: "ABC123456789",
  name: "My Site",
  productFeedUrl: "https://example.com/product-feed.xml"
}
Attribute Type Description
siteKey OR cdnKey string Site key of the site to set or CDN key of the organization to create new site for (sitekey cannot be generated for an older, manually created organization - see organization manipulation, prefix parameter. Use siteKeyPrefix parameter for those).
siteKeyPrefix optional string Prefix for random site key for older, manually created organizations (see above)
test optional boolean Set for test site to true
name string Name of the site
merchantType optional string Recommender type of the shop, if any
merchantId optional string Recommender system ID
container string DOM container of the hero (.class or #id format)
containerWidth integer Intended width of the container
containerHeight integer Intended height of the container
bannerWidth integer Initial width of the carousel
bannerHeight integer Initial height of the carousel
mobileBannerWidth integer Initial width of the carousel on mobile devices
mobileBannerHeight integer Initial height of the carousel on mobile devices
designParameters object Design parameters for the site. See Design Parameters
dryRun optional boolean If true, will not save the result, just return it

Response is like for the GET request.

Delete

HTTP Request

  DELETE https://api.producthero.com/admin/site?siteKey={Site Key}

siteKey: identification token of the given site to delete

Manage Heroes

Heroes are carousel variants. Only one of them can be live. The _live hero will show up in the carousel. For using your carousel you need to save at least one hero under a Site.

Get information about an existing hero.

HTTP Request

  GET https://api.producthero.com/admin/hero?id={Hero ID}

id: ID of the given hero

Create / modifiy site

HTTP Request

  POST https://api.producthero.com/admin/hero

Head:

  Content-Type: application/json

Body:

{
  id: "1",
  name: "My Hero"
}
Attribute Type Description
id OR siteKey string ID of the hero to set or site key of the site to create new hero for
name string Name of the hero
goLive optional boolean If set to true and NOT dry run, hero goes live after save
dryRun optional boolean If true, will not save the result, just return it

Response is like for the GET request.

Once you've saved a Hero the carousel.js is available under https://static.cdn.producthero.ai/{siteKey}/carousel.js.

Delete

HTTP Request

  DELETE https://api.producthero.com/admin/hero?id={Hero ID}

id: ID of the given hero to delete

Manage Users

You can add / remove users for a specific Organization

Get information about an existing user.

HTTP Request

  GET https://api.producthero.com/admin/user?email={User's email}

Create / modifiy

HTTP Request

  POST https://api.producthero.com/admin/user

Head:

  Content-Type: application/json

Body:

{
  id: 1,
  name: "Jane Doe"
}
Attribute Type Description
id OR cdnKey string ID of the user to set or CDN key of the organization to create new user for
name string Name of the hero
email string Unique email address of the user
password optional string New password for the user
active optional boolean Set to false to not activate the user immediately
dryRun optional boolean If true, will not save the result, just return it
invite optional boolean If true and NOT dry run, will send an invitation email to the user's email address after save

Delete

HTTP Request

  POST https://api.producthero.com/admin/user?id={User ID}

id: ID of the given user to delete

Design Parameters

The Draw mechanism calculates designs and compositions based on the designPrameters. Here you can define all the brand colors, fonts and spacings. The unit of sizing is pixels. If a banner is shown on a page with the same width and height as they were defined in its Site setting block, sizes defined here are exactly pixel accurate, but in other cases the Draw mechanism use these values just to get the correct aspect ratio. If you have a responsive site where block sizes change all the time Product Hero adopts new dimensions in a snap.

Structure

{
  "version":"1.0",
  "settings":{},
  "colors":[],
  "fonts":{},
  "margin":{},
  "message":{},
  "subject":{},
  "price":{},
  "msrp":{},
  "cta":{},
  "sticker":{},
  "patterns":[]
}

Common Settings

Property Description
allowAnimation Enable or disable animations in the banner
useBrandAsSubject Use brand name instead if category name at the top of the banner
pricePlacementPreference Priceblock can be placed in the Sticker or above or near the CTA. Possible values: false, "near cta", "above cta")
snapCroppedImagesToEdges Cropped non-isolated photos with diverse background should snap to banner edges (e.g. Photo of a kitchen)
productImageEdgeRepeater Turn on the mechanism that will stretch image edges to get smooth, continuous background
messageHeightModifier Message block always wants to fill all the space left after all the elements are placed on the banner. This modifier is a vertical scale ratio to decrease Message container height to keep design airy.
animations Define animation types

Example

"settings": {
    "allowAnimations": true,
    "useBrandAsSubject": false,
    "pricePlacementPreference": false,
    "priceAnchoring": true,
    "snapCroppedImagesToEdges": true,
    "productImageEdgeRepeater": "edgeRepeater",
    "messageHeightModifier": "0.95",
    "animations": {
        "slide": "slide-in",
        "textBlocks": "slide-in",
        "sticker": "flip",
        "image": "hologram",
        "priceBlock": "slide-in"
    }
}

Colors

This block is an array of color schemes. "stroke" property is optional. Background can be "transperent" or false.

Example

"colors": [
  {
    "cta": {
        "background": "#E9E9E9",
        "text": "#1BA4DE",
        "border": false
    },
    "sticker": {
        "background": "#1BA4DE",
        "text": "white",
        "border": "white"
    },
    "subject": {
        "background": "auto",
        "text": "#2F4858",
        "stroke": "white"
    },
    "message": {
        "background": false,
        "text": "#151d4c",
        "stroke": "white"
    },
    "price": {
        "normal": "#303532",
        "sticker": "rgba(255,255,255,0.95)"
    },
    "msrp": {
        "normal": "#f71c39",
        "sticker": "rgba(255,255,255,0.5)"
    },
    "background": "#FFFFFF",
    "gradientOverlay": "#9EBAC5",
    "pattern": "#9EBAC5"
  }
]

A color scheme can have backgroundImage block. This scheme will be only chosen if the product image's background is transparent. Background image and pattern can not be combined, so patterns will be ignored by this scheme.

"backgroundImage": {
    "image": "https://example.com/scheme-background-image.jpg",
    "css": {
        "backgroundSize": "cover",
        "backgroundPosition": "center center"
    }
}

Fonts

Here you can set up the font types for the elements. You can use Google fonts or custom fonts. If you are interested in adding custom fonts, please contact us at want@producthero.ai.

Example

"fonts": {
    "cta": {
        "family": "Open Sans Condensed",
        "weight": "700"
    },
    "subject": {
        "family": "Open Sans Condensed",
        "weight": "300"
    },
    "message": {
        "family": "Open Sans",
        "weight": "400"
    },
    "price": {
        "family": "Open Sans",
        "weight": "700"
    },
    "msrp": {
        "family": "Open Sans",
        "weight": "300"
    },
    "badge": {
        "family": "Open Sans Condensed",
        "weight": "700"
    }
},

Margin

This will be the distance the Draw mechanism will try to keep from edges, between elements, etc.

Example

"margin": {
    "normal": "50",
    "mobile": "60"
}

Subject

Subject is the small caption on the top of the banner. Subject usually displays category or brand name.

Example

"subject": {
  "fontSize": {
      "normal": 20,
      "mobile": 20
  },
  "stroke": 5,
  "enabled": true
}

Message

Message is the main large text on a banner, practically the name of the product. It has no size since it tries to grow into all the space that left.

Example

"message": {
  "stroke": 5,
}

Price, MSRP

The size of price elements fit in CTA or Sticker, depending on the chosen layout. You can define a currency symbol or other prefix or postfix that attaches to the price block.

Example

"price": {
  "prefix": "€ ",
  "postfix": false
},
"msrp": {
  "prefix": "€ ",
  "postfix": false
},

CTA

CTA is the button on the banner. You can set up its CSS and text as follows:

Example

"cta": {
  "normal": {
    "border": {
        "size": 0,
        "radius": "4"
    },
    "fontSize": "26",
    "padding": {
        "top": "16",
        "right": "20",
        "bottom": "16",
        "left": "20"
    }
  },
  "mobile": {
    "border": {
        "size": 0,
        "radius": "4"
    },
    "fontSize": "26",
    "padding": {
        "top": "16",
        "right": "20",
        "bottom": "16",
        "left": "20"
    }
  },
  "allowGradient": true,
  "defaultText": "BUY NOW",
  "icon": false
},

Sticker

Set Sticker design for both Badge and Price Tag form.

Example

"sticker": {
  "normal": {
    "rotation": {
      "priceTag": -5,
      "badge": 0
    },
    "border": {
      "size": 0,
      "radius": 0
    },
    "size": {
      "priceTag": {
        "width": 110,
        "height": 70
      },
      "badge": 85
    },
    "shadow": {
      "x": 2,
      "y": 5,
      "blur": 4,
      "alpha": 0.1
    },
    "padding": {
      "top": 7,
      "right": 10,
      "bottom": 7,
      "left": 10
    }
  },
  "allowGradient": true,
  "mobile": null,
},

The above example does not show it as "mobile" is set to null, but you can define different values for mobile devices with that key.

For saving a desingParameters please see Client Management API

Product Feed Options

Coming soon...