Fanplayr Docs

English

日本語
Español
Italiano

English

日本語
Español
Italiano

Appearance

Legacy Catalog Format ​

Legacy format

This is the legacy catalog format, documented here for reference. New integrations should use the current format, which is more expressive and better supported.

Definition ​

A product catalog represents the entire collection of products that are available for purchase on an e-commerce store.

Each catalog item is represented as a JSON object with the following structure:

javascript
{
  "id": "805371A",
  "itemGroupId": "805371",
  "categoryHierarchies": [
    { "categories": ["Women", "Shoes"] },
    { "categories": ["Sports & Fitness", "Shoes"] }
  ],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brand": "Designer Brand",
  "languageCode": "en",
  "productMetadata": {
    "stockState": "IN_STOCK",
    "availableQuantity": 30,
    "exactPrice": {
      "originalPrice": 119.99,
      "displayPrice": 89.99
    },
    "currencyCode": "USD",
    "canonicalProductUri": "https://www.store.com/shoes/red-shoes",
    "images": [
      {
        "uri": "https://www.store.com/images/805371.jpg",
        "width": 500,
        "height": 500
      }
    ]
  }
}

INFO

The above example includes line-breaks for readability. In a catalog file, each product must be a single JSON-encoded line. The file must also be encoded in UTF-8.

javascript
{"id":"805371","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":119.99,"displayPrice":89.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/805371.jpg","width":500,"height":500}]}}
{"id":"805372","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Green Shoes","description":"Fancy green shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":148.99,"displayPrice":129.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/green-shoes","images":[{"uri":"https://www.store.com/images/805372.jpg","width":500,"height":500}]}}

Properties ​

id ​

  • Type: String
  • Required
  • Maximum size: 128 bytes

This ID must be unique among all catalog items within the same catalog. It must be the same ID that is tracked with product page views in your Fanplayr integration.

itemGroupId ​

  • Type: String
  • Required (depending on catalog level configuration)
  • Maximum size: 128 bytes

Product variant group identifier, also known as the "master" product identifier. This links all related product variants together for prediction results.

Either all catalog items must have a value for itemGroupId or none of them can. You cannot import catalog data with itemGroupId set for some items but not others. This field is required when using the Master/Master or Variant/Master catalog level.

categoryHierarchies ​

  • Type: Array
  • Required (at least one entry is required)
  • Maximum size: 1,000 bytes (when encoded as JSON)

Catalog item categories. This field is repeated to support a product belonging to several parallel category hierarchies.

For example, if a shoes product belongs to both Women > Shoes and Sports & Fitness > Shoes, it could be represented as:

javascript
"categoryHierarchies": [
  { "categories": ["Women", "Shoes"] },
  { "categories": ["Sports & Fitness", "Shoes"] }
]

title ​

  • Type: String
  • Required
  • Maximum size: 500 bytes

The product title.

description ​

  • Type: String
  • Maximum size: 500 bytes

The product description. Can help improve the recommendation model.

brand ​

  • Type: String
  • Maximum size: 100 bytes

The brand or manufacturer associated with the product.

languageCode ​

  • Type: String
  • Required

The language of the title and description. Use language tags defined by BCP 47. Supported language codes include: "en", "es", "fr", "de", "ar", "fa", "zh", "ja", "ko", "sv", "ro", "nl".

productMetadata ​

  • Type: Object
  • Required

Contains the properties stockState, availableQuantity, exactPrice, currencyCode, canonicalProductUri, and images.

stockState ​

  • Type: Enum
  • Nested under: productMetadata
  • Required

The availability of the product. Must be one of:

  • IN_STOCK — Item in stock.
  • OUT_OF_STOCK — Item out of stock.
  • PREORDER — Item available to pre-order.
  • BACKORDER — Item temporarily out of stock but available to back-order.

availableQuantity ​

  • Type: Number
  • Nested under: productMetadata

The remaining quantity of the item available for purchase.

exactPrice ​

  • Type: Object
  • Required

Contains the properties originalPrice and displayPrice.

originalPrice ​

  • Type: Float
  • Nested under: productMetadata.exactPrice
  • Required

The original price of the item before any discounts.

displayPrice ​

  • Type: Float
  • Nested under: productMetadata.exactPrice
  • Required

The current price of the item after any discounts.

currencyCode ​

  • Type: String
  • Required

The currency code for all item prices. Use the three-character ISO 4217 code (e.g. "USD", "AUD", "GBP").

canonicalProductUri ​

  • Type: String
  • Required

The base URI of the product. If your product has different URIs for different colours or sizes, provide the URI for the base product without variant parameters where possible.

images ​

  • Type: Array
  • Required (at least one image is required)

An array of product images. Only the first image is displayed in recommendation widgets. At least one image is required.

Each image should be an object with the following structure:

javascript
{
  // Required. URL of the image. Maximum size: 1,000 bytes.
  "uri": "https://www.store.com/images/805371.jpg",
  // Optional. Image width in pixels.
  "width": 500,
  // Optional. Image height in pixels.
  "height": 500
}

tags ​

  • Type: Array of strings
  • Maximum size: 500 bytes (combined)

Optional tags to associate with the catalog item. Each must be a UTF-8 encoded string. The combined length of all tags for a single item must not exceed 500 bytes.

itemAttributes ​

  • Type: Object
  • Maximum size: 1,000 bytes (combined)

Optional extra attributes to include in the recommendation model. For example, for retail products this could include product style, colour, etc. These attributes provide additional signals for recommendation models.

Item attributes should be divided into categorical and numerical sets with the following structure:

json
"itemAttributes": {
  "categoricalFeatures": {
    "colors": {
      "value": ["red", "blue"]
    },
    "sizes": {
      "value": ["S", "M", "L"]
    }
  },
  "numericalFeatures": {
    "lengths_cm": {
      "value": [2.3, 15.4]
    },
    "heights_cm": {
      "value": [8.1, 6.4]
    }
  }
}

customData ​

Custom data can be added to a product for use with specific Fanplayr features.

For example, to set keywords and colour chips in Personal Shopper or Product Tag Explorers:

json
"customData": {
  "keywords": [
    { "text": "ON SALE", "bg": "#ff0000", "fg": "#fff" },
    { "text": "Special Brand" }
  ],
  "colors": ["red", "#00ff00"]
}

Catalog file format ​

The catalog file must meet the following requirements:

  • Each catalog item must be formatted using the JSON structure described above.
  • Each catalog item must be contained on a single line (JSONL format).
  • The total file size must not exceed 50 MB uncompressed. If your catalog exceeds this, split it and import it in multiple files.
  • All items must use the same language and currency. It is not possible to mix languages or currencies within a single catalog, as this would affect AI model training. Manage separate catalogs if your store has multiple views with different languages or currencies.

The following is an example of a catalog file with 2 items:

javascript
{"id":"PRODUCT_1","categoryHierarchies":[{"categories":["Women","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":30,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_1.jpg","width":500,"height":500}]}}
{"id":"PRODUCT_2","categoryHierarchies":[{"categories":["Men","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Blue Shoes","description":"Fast blue shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":17,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/blue-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_2.jpg","width":500,"height":500}]}}

Catalog levels ​

Before importing your catalog for the first time, you must determine whether to track master items or variants with your user events on site, and whether to return master items or variants with predictions. Fanplayr will assist in configuring your integration.

Master items represent a group of similar items (a SKU group). For example, a master item might be "V-neck shirt", with variants such as "Brown v-neck shirt, size XL" and "White v-neck shirt, size S". Masters and variants are sometimes described as "parent" and "child" items.

The possible catalog level configurations are:

  • Variant/Variant — Capture variants with user events and return variants with predictions.
  • Master/Master — Capture master items with user events and return master items with predictions.
  • Variant/Master — Capture variants with user events and return master items with predictions.

Copyright © 2011-present Fanplayr Inc