We have launched our new documentation. Please head here to read it.

Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

  • Prepare your Schema
  • Prepare your Catalog
  • Upload your Feed

  • Full Feed Upload
  • Delta Feed Upload
  • Check Product Count

  • JavaScript Based Integration
  • HTML Based Integration

  • Introduction to GTM
  • Requirements

  • Introduction
  • Events
  • API Integration

  • Browse Endpoint
  • Authentication
  • Header
  • Request Parameter
  • Response Components
  • Explanation Request Parameter

  • PDP API Format

  • Taxonomy API Format
  • Taxonomy Feed API

  • System Requirements
  • Install SDK
  • Initialize SDK
  • Unbxd Commerce Search
  • Integrating Unbxd Autosuggest
  • Unbxd Analytics
  • Unbxd Browse
  • Unbxd Recommendations
  • Sample App

  • Installation
  • Unbxd Analytics
  • Unbxd Commerce Search
  • Unbxd Autosuggest
  • Unbxd Browse
  • Unbxd Recommendations
  • Sample iOS App

  • Libraries
  • Quickstart
  • Authentication
  • Types of Pages to Render
  • Configuring the Page
  • Callback Functions
  • Helper Functions
  • Available Configurations

  • Installation
  • Configuration
  • Components

  • Composer
  • Direct Plugin Feed Upload
  • Authentication
  • General Settings
  • Configuration
  • Catalog Sync
  • Catalog Sync Information
  • Product Feed Generator
  • Feed View
  • Indexing Queue View
  • Analytics Integration
  • Upgrade
  • Uninstall

  • Installation
  • Configuration
  • Configure Feed
  • Cron Job
  • Features
  • Uninstall

Feed Creation

Once you have your site key, you’re ready to upload your product catalog. A product catalog is a detailed list of products and their characteristics in a store.

 

This page walks you through the process of understanding what a schema and a catalog is, what and how you’ll need to upload both to seamlessly integrate them with our search solution.

STEP 1
STEP 2
STEP 3

Prepare Schema

Prepare Catalog

Upload Feed

TIP: Customers using Magento 2, Shopify, and Hybris can use our platform plugin to upload their feed and integrate Analytics.

Prepare Schema

A schema establishes the properties of each attribute within a product catalog and determines the various type of functions and operations that can be supported for each attribute. For example, a numeric dataType will allow operations such as less than and greater than and range facets; whereas a text dataType will support operations such as contains and support text facets.

Schema Format

The schema is part of a larger JSON feed file and is defined by the “schema” node. Each JSON object within the schema represents a field within your catalog. 

 

Each field must contain the following four properties:

  • fieldName (Mandatory)
  • dataType (Mandatory)
  • multiValued (Mandatory)
  • autoSuggest (Mandatory)
  • isVariant (Optional)
  • id (Optional)

NOTE: While we recommend you upload both the schema and catalog as a unified JSON file, you can also upload the schema as a separate file.

  • fieldName

The fieldName specifies the name of the attribute such as title, color, and brand. Field names are case-sensitive; should start with an alphabet or underscore; can only contain alphanumeric characters, hyphens and underscores; cannot contain special characters, spaces, or end with an underscore.

 

  • id

The id in schema specifies a numerical identifier for an attribute in the catalog. Useful when product feeds may have the fieldID instead of the fieldName.

 

  • dataType

A dataType defines the type of value a specific field can have. We support the following dataTypes.

 

dataType

Format

Description

Searchable 

text

String

Used for text fields such as title, color, brand, style etc.

yes

longText

String

Used for large text fields such as description and summary. Not every catalog will contain fields required to be marked as longText.

yes

decimal

Decimal

Used for fields that take decimal values such as price, discount, etc.

–

number

Numeric

Used for fields that take numeric values such as, quantity, orderCount, viewCount, etc.

–

link

URL (string)

Used for fields that take URL strings as values such as, productUrl, imageUrl, etc.

–

date

ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ)

Used for fields that take date values such as, createdAt, updatedAt, etc.

–

bool

true/false

Used for fields that take boolean values such as, availability, hasBanner etc.

–

sku

String 

Used for fields that uniquely identify a product such as sku, product number, part number etc.

yes

path

String

Used for fields that are hierarchical in nature. Eg, categoryPath. Different values within a hierarchy are separated using “>”. Eg, “Men>Shoes>Casual Shoes”

–

facet

String

Internal reserved schema type used by Unbxd when processing for spelling, stemming, or tokenization is not required; not to be used by customers unless directed by Unbxd.

–

nsku

String 

This data type is mainly used for B2B catalogs and supports any substring match, including prefix match, suffix match along with special character handling, as well as camel case and alpha-numeric searches.

yes

 

NOTE: Data Types of fields that are made searchable display those products on the search results page. Data Types that are not searchable can be used for filtering, sorting, and faceting.

  • multiValued

A multiValued attribute determines if a field can have multiple values for a product. For example, a Nike shoe can be considered sporty and casual in which case you could send multiple values for a style field: “style”:[“casual”,”sport”]. However, a field such as brand would be single-valued: “brand”:”Nike”. To enable a field to accept multiple values, set multiValued to true, otherwise to false.

 

  • isVariant

Only required for catalogs with variants, if an attribute is a variant field instead of a parent product field, set it to true, else set it to false. 

 

Sample Schema

{
"feed": {
        "catalog": {
            "schema": [{
                "fieldName": "vColor",
                "id": "76678",
                "dataType": "text",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }, {
                "fieldName": "vSize",
                "dataType": "text",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }, {
                "fieldName": "vImages",
                "dataType": "link",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            },
{
                "fieldName": "vPrice",
                "dataType": "decimal",
                "multiValued":true,
                "autoSuggest":false,
                "isVariant":true
            }]
        }
    }
}

Schema Upload Process

You can upload a schema using APIs with the exception of instances where any post-processing is performed by Unbxd on your schema which requires an SFTP upload.

 

Every schema upload appends to an existing schema, if any. You can update the characteristics 

In case the schema has fields that are already found within an existing schema, the property values of the existing fields are updated. Similarly, when the new schema has new fields that are not found within an existing schema, the existing schema appends and adds the new fields. It is currently not possible to delete existing fields through the schema API.



API Parameters

The API parameters along with sample request and response are defined below:



Best Practices

To ensure your schema is uploaded and integrated seamlessly, here are some practices we recommend:

 

  1. Schema is required for all fields (except for internal fields created by Unbxd)
  2. Schemas not adequately defined will be rejected.
  3. Ensure your schema file is in JSON format.
  4. Field names are case-sensitive.
  5. Field names should start with alphabets or underscore. It can be alphanumeric, can have hyphens and underscores. It cannot contain special characters, spaces in between words, or end with an underscore. 
  6. Do not send fields that have null values.

Prepare Catalog

In this section, we define the product catalog and its attributes and different ways of sending your catalog to the Unbxd system. The catalog file contains a list of all your products and its attributes. The information associated with products is managed by search engines using attributes or fields.

 

Some generic attributes considered universal across businesses are:

  • uniqueID (required)
  • title
  • price
  • description
  • category
  • imageURL
  • productURL
  • currency
  • brand
  • color
  • price
  • availability

Broadly, the typical feed will contain many other attributes, which will have display, searchable, merchandisable, and unique attributes.

Fields

The product attributes store information related to a particular product. The attributes in a catalog can be classified into following categories :

  • UniqueId
  • Feature Fields
  • Custom Fields

 

UniqueID

UniqueId is a unique identifier that is associated with every product in the catalog and it is used to uniquely identify a product. Also known as a Stock Keeping Unit (SKU) or a productID (pid), the unique identifier helps the search engine keep a track of sales of a particular product and maintain your store’s inventory. The UniqueId attributes may not be visible to the shoppers and can remain completely hidden.

NOTE: Specifying 'UniqueId' for a product is mandatory.

Feature fields

Feature fields are a list of Unbxd fields that are necessary for majority of basic functionality to work and are expected to be included in your catalog.

fieldname multiValued dataType Description
uniqueId (mandatory field) false text Unique identifier of a product. It cannot have special character except ‘-’ and ‘_’
variantId false text Unique identifier of a variant (if present). It cannot have special character except ‘-’ and ‘_’. It needs to be unique across entire product catalog.
variants true text Field holding all the variants for a product.
title false text Title or name of a product.
price false decimal(or double) Price of a product.
description false longText Description of a product.
category true text Name of the category a product belongs to.
subCategory true text Name of the sub-category a product belongs to.
categoryPath (mandatory field) true path The category hierarchy of a product separated by  “>” such as “Men>Shoes>Casual Shoes” If categoryPathId below is included, categoryPath is not required as it will be generated automatically by the system
categoryPathId true text For catalogs that have category ids available, categoryPathId represents the mapping between category names and category ids. IDs and Names need to be separated using “|”. For example, “cat100|Home>cat101|Luggage & Travel Accessories>cat102|Travel Accessories”
imageUrl false link URL of a product image.
productUrl false link URL of the Product Detail Page (PDP) of a product.
currency false text Currency of a product.
brand false text Brand of a product.
color true text Color of a product.
availability false bool The availability of a product in “true”/“false” format.
sku false sku Unique identifier for an item.
gender false text Gender for a product.
size true text Size of a product.
rating false decimal Rating for a product.
discount false decimal Discount on a product.
sellingPrice false decimal Selling price of a product.

 

NOTE: If your catalog contains a feature field with a different name, you can either map it to the corresponding feature field from the Unbxd Console or rename your existing field to a feature field in the schema.

Custom fields

Attributes that are not part of our list of Feature Fields but part of your product catalog are known as Custom Fields. These attributes and their properties are included in your schema.

Like Feature fields, our search engines use these attributes to power product discovery on your web page.

Variants

Variants are products that share the same SKU or productID (PID) but have at least one or more fields, like color, size, patterns that are different from the other fields of the same PID. These products will be displayed as a distinct product in the search results page.

Once your catalog has updated information related to variants, you can add variants to your existing feed. In each of the illustrations below, variants are configured to appear differently. 

 

Illustration 1 : The HDMI cable has 5 variants – color, size, gauge, quantity, and output.

 

Illustration 2: In the illustration below, the product ‘Mango Badam’ has 1 variant – size. The PLP chooses to display the product as two separate entities here.

 

Illustration 3: In this illustration, the skirt has two variants – color and size. The other fields like title, description, fabric/material, price are the same.

 

Best Practices

 

To ensure your feed is uploaded and integrated seamlessly, here are some practices we recommend:

  • Ensure every product has the associated uniqueId.
  • Ensure all attributes are defined in the schema.
  • Ensure your catalog file is in JSON format.
  • Field names are case-sensitive.
  • Field names should start with alphabets or underscore. It can be alphanumeric, can have hyphens and underscores. It cannot contain special characters, spaces in between words, or end with an underscore.
  • Do not send fields that have null values.

Upload Feed

We support three methods of feed upload:

  • Rest APIs: Use our custom REST APIs to upload your feed directly
  • Secure File Transfer Protocol: Upload your feed through an SFTP. Feed files uploaded on SFTP servers are transformed and uploaded to Unbxd servers. SFTP upload supports feed files in CSV, JSON and XML formats. 
  • Platform Extensions: Our platform extensions can be used to upload feed seamlessly. Integrate our Magento 2 , Shopify or SAP Hybris plugin to automate catalog transfer from these platforms.

Copyright 2020 © Unbxd Inc, All Rights Reserved. Privacy Policy