Catalog import

In the following sections we explain why and how you have to set up your product catalog and general configuration. This chapter is divided in two sections:

  • Catalog file configuration: This section describes in detail how to configure product feed management.

  • Basic parameters: lists the standard parameters you should set up for TasteHit to function properly.

  • Special features: Advanced features which can help you fine-tune your product feed configuration.

Catalog files management

Before TasteHit can generate graphical product selections in the form of widgets or personalized emails it needs to have access to a product catalog and be able to import it. This product catalog, also called "product feed" is a set of files which are usually exported by your online shop's Content Management System (CMS) automatically and on a regular basis, and made publicly accessible. TasteHit then automatically imports these files at regular intervals. TasteHit supports all the following standard formats: CSV, XML and JSON.

The configuration of the export is independent from TasteHit and has to be done on your side before you start installing TasteHit. Most of the time we simply reuse standard exports which are already in place: Google Shopping, Criteo, Shopzilla, Amazon, Zalando, Lengow, Shopping flux, Product Live, and most of the standard exports you can think of.

The configuration of the import procedure is done in the TasteHit dashboard, in the catalog settings section.

Catalog files

Every time you change something in the dashboard, you have to click on the "Save All" button at the top right of the screen to save your configuration in the current screen:

Catalog files

If you made changes but do not want to save anything, click on "Go back to saved version" or simply leave the page without saving.

Field types

Mandatory fields

The feed you export needs to contain the following minimal information for each product for the catalog to be successfully imported:

  • Unique ID: The unique identifier of a product inside the catalog. This value needs to be unique. Ideally this ID should be easily found on product pages, either inside the URL (https://my-shop.com/products/blue-jeans-p001.html?variation=2, where p001 is the Unique ID).

  • Page URL: the exact URL to reach the product page. It should be unique, just like the Unique ID, but it is not mandatory.

  • Image URL: The exact URL to the picture of the product. This picture can be in any format (jpg or png preferred) the format of the picture needs to make sense compared to the size of the pictures you want to have in your TasteHit widgets. For example having 100x100 images in your feed while you want to display large retina-compatible pictures in your widgets will not work. If you put links to high-definition images in your feed but want widgets with much smaller images of variable sizes, we can take care of optimizing, scaling and hosting your images with a powerful CDN. Please contact us if this is something you need (additional paid service).

Optional fields

The three fields described above will only allow a very basic graphical configuration and will not allow any filters to be configured in widgets. A standard product feed usually contains the following properties for each product:

  • Title: the title given to the product. This text needs to be short (~50 characters) as it will be automatically placed under the product picture inside widgets if this option is selected.

  • Subtitle: same as the title, but can be longer (~100 characters).

  • Description: the description of the product can be longer. Like the two fields above, it can contain HTML tags, which will be stripped at import time.

  • Price: the base price of the product which will be displayed to the visitor, before discount. The currency is not important here as it is set in other optional fields. We will try and detect a numerical value in this field in any case. For example if the field contains "10tastehit", the value parsed will be 10. If the field contains "tastehit10", the value will not be parsed and the price of the product will not be available.

  • Sale price: the price at which the product is sold (after discount). In case a discount is applied to the product the sale price must be lower than the price.

  • Category: the category to which the product belongs.

  • Quantity: the number of products in stock.

  • Type: the type of the product, a field similar to category, usually segmenting products into fewer groups of larger amounts of products.

  • Brand: the brand of the product. If it is activated, it appears in widgets at the bottom of the text description, after the title, description and price.

  • Color: the color of the product if it is a parameter which makes sense.

  • Main personality: mainly for movies (actor/producer) or books (author), used mainly for filters

Custom fields

TasteHit can deal with any number of fields per product. Custom parameters can be included and will be used by the TasteHit platform in different ways (displaying in widgets, used for creating filters). Here are examples of common fields that are included in product feeds:

  • Availability: whether a product can be bought or not. It can be any value and is mainly used in filters.

  • Condition: whether the product is new or not.

  • Manufacturer: the manufacturer of the product.

Your product feed export should be accessible at a publicly reachable URL (HTTP(S) or (S)FTP), but can be password-protected. Once an export is configured on your site, you can start configuring the import in the following section.

Format-specific setup

We support most standard product feed formats. Please refer to the following instructions for the format you are using and use the live chat in case you have questions specific to your shop.

CSV format

If your catalog is in CSV format, you have to add the URLs of all the files in the Catalog files section and select CSV in the Catalog Files Format input box. A typical setup for a CSV catalog with a single product feed file would look like this:

CSV Catalog file setup

You can have one catalog file, you can have several files and all of them are part of the same feed, or you can have several files, each one of them representing a specific language and/or location. If you have several files (whatever the case is), all of them need to have the exact same format (same number and order of columns).

A typical example of a catalog with many files would look like this: CSV Catalog file multilanguage setup

The content of any of the files above would look like the following:

1
2
3
item_pid|brand|color|type|saison|price|description|image_url|item_url|sale_price
p0001|the best brand|white|W16|199|Nice pants|https://www.my-shop.com/static/img/p0001.jpg|https://www.my-shop.com/products/nice-pants-p0001.html|189
p0245|the second best brand|white|S17|249|Blue shoes|https://www.my-shop.com/static/img/p0245.jpg|https://www.my-shop.com/products/nice-pants-p0245.html|209

Once your files are listed in the Catalog files, you need to set up the columns. You can list the columns, or simply copy-paste the first line of your CSV file, in the Your CSV Columns Names, then click on the Refresh button.

Your columns will be listed vertically and a mapping will be generated between the name of your columns and the standard naming used at TasteHit. In a final state, this mapping configuration would look similar to this:

CSV Column mapping

The active checkbox is a specific option for CSV files. If it is checked, it means that this field will be available for use in widget filters. If the box is unchecked, it will not be possible to create filters based on this field. The reason is that CSV catalogs tend to be larger in size than CSV and JSON as all products will include all CSV fields (as products are read in full lines and include all fields/columns in the line). Unchecking the active checkbox is a way to avoid reading certain fields, increasing the overall performance of the site.

The CSV-specific parameters you need to configure are the following:

CSV Specific parameters

These fields simply define how the CSV file should be read:

Field delimiter

The character which stands between each field. In the previous example, the character is: | (pipe).

Quote type around fields

In some CSV files, quotes are used around each field: "field 1"|"field 2" even though it is safer not to use them while having a good delimiter.

Type of encoding

The encoding used in the file. You can find or tune the encoding in your text editor. By default, if you are on a Linux or MacOS system, leave it to UTF-8. If you are on a Windows system and you see strange characters appearing in your widgets, set it to Latin1.

Skip first line

If the first line of your file(s) contains the column names, check the box. If your first line contains information about a product, leave this box unticked.

XML format

If your catalog is in XML format, you have to add the URLs of all the files in the Catalog files section and select XML in the Catalog Files Format input box. A typical setup for a XML catalog with a single product feed file would look like this:

XML Catalog files

Just like for the CSV feed, you can have one or more files, with or without language/location parameters. The big difference with CSV files is that not all parameters have to be set for all items (some products may miss some properties).

Map the TasteHit parameter names and your XML tag names in the Product properties table:

XML Column mapping

A typical XML product feed would look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?xml version="1.0" encoding="UTF-8"?>
<products>
  <product>
    <identifiant_unique><![CDATA[p0001]]></identifiant_unique>
    <url_produit><![CDATA[https://www.my-shop.com/products/nice-pants-p0001.html]]></url_produit>$
    <url_image_1><![CDATA[https://www.my-shop.com/static/img/p0001.jpg]]></url_image_1>
    <couleur><![CDATA[bleu]]></couleur>
    <brand><![CDATA[the best brand]]></brand>
    <price><![CDATA[199]]></price>
  </product>
  [...]
</products>

The Base XML Tag specifies the tag name of the highest level object which contains all the product information. In the previous example, products contains a list of product subobjects, each one containing all the information (corresponding to the tag names we specified above) for a specific product.

In the XML format, each field can have specific options:

XML Field Options

In addition to the field name and its mapping to a TasteHit parameter name, you can specify the following options for each field:

  • This field is an array of values: when this box is checked, this field will be read as an array of several values rather than a single value. It is useful for array fields, such as <available_sizes><![CDATA[35,36,37,38,39,40,41,42]]></available_sizes>.

  • This field will be sent with API responses as: this parameter changes the name of the field when TasteHit is queried via the API. The previous parameter available_sizes and its value can be returned via the api with another name, e.g. sizes. This parameter is useful for making APIs compatible while avoiding changes in the code.

  • This field will be sent as a single value: if the field is an array, but it is expected that the API returns a single value, ticking this box will make the API return the first value of the array.

  • Multi language: this field is only used in case the language is contained in the product parameters. Usually this is not the case as the language and location are set per file.

JSON format

If your catalog is in JSON format, you have to add the URLs of all the files in the Catalog files section and select JSON in the Catalog Files Format input box. A typical setup for a JSON catalog with a single product feed file would look like this:

XML Catalog files

A typical JSON feed which would be parsed using the above configuration would look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[
  {
    "product_id":"p001",
    "product_url":"https://www.my-shop.com/products/nice-pants-p0001.html",
    "product_first_image":"https://www.my-shop.com/static/img/p0001.jpg",
    "product_master_category_name":"category 1",
    "product_created_at":"2014-02-04 08:29:23",
    "product_brand":"the best brand",
    "product_name":"first product"
  },
  [...]
]

The field options which are used in JSON are the same as the ones described in the XML, except for multi language (as a property inside the JSON file) which is currently not supported for the moment. If you want to have multi-language using JSON files, you have to create one file per language/location like it is described in the CSV multi-language setup.

Additional parameters

Basic

The following list gives explanations on the basic parameters you can find in the catalog settings page.

Domain

The full domain of your shop, including protocol (http or https), subdomain (www) and extension. The trailing slash is optional. Here are a few examples: https://www.mycompany.com, http://mycompany.com, https://shop.mycompany.de/. This parameter is used for security. If your shop uses multiple languages with different domains, simply add one of your domains here.

The logo is an absolute image URL linking to a logo of your shop. One of the supported formats must be used (.png, .jpg). This parameter is optional and will only appear at the top-left corner of the TasteHit dashboard. This is an optional field.

Username and password

If your catalog files are password-protected (using .htaccess for HTTP(S) or standard username/password for (S)FTP). Enter your username and password in these fields. This is an optional field.

Image URL prefix

If your images have a relative path, you can add a prefix which will be prepended to all the images found in the catalog. For example if your image fields are all in the format /static/img/p0001.jpg and you want them to look like https://www.my-shop.com/static/img/p0001.jpg, you should add https://www.my-shop.com in this field.

Default mail language

In case your catalog and shop are configured with multiple languages, you need to specify which language should be used when sending emails. If you do not specify it, or if the information in the right language cannot be found, the language specified in this field will be used. This is an optional field.

Currency Symbols

This parameter lets you define the currency symbols you want to use for different languages and locations as the widgets are displayed. When the catalog is imported, Price and Sale price properties are imported as numbers, which means that if the currency is included inside the parameter, it will be stripped. To make sure the correct symbol appears next to product prices inside widgets, set the correct symbol ($, €, CHF, or anything else) for every language/location combination. Placement can be Left (the currency comes before the price) or Right (the currency comes after the price).

Here is an example of how this parameter can be used:

Currency symbols

In this example the first line indicates that for language "fr" and location "CH", the symbol "CHF" will be used and placed before the price. You would see something like 99,00CHF under products in widgets. The price decimals and the decimal separator are configured in the widget graphics configuration.

Import filters

You may want to prevent TasteHit from displaying some products in all widgets. This can be the case if you export products in your feed which are not available (sold out). In that case you can create an import filter and tell TasteHit to exclude specific products from all widgets. Here is an example:

Catalog import filters

This filter will mark all products which have their g:availability parameter set something else than "in stock". If a product is "in stock", it will be available to show to users. If a product is "out of stock", or "available soon", it will not be displayed in any widget.

Warning

It is important to export in your feeds all products which are visible on the shop, even those which are out of stock or unavailable. The reason is that you still want TasteHit to collect behavioral data on these products to better train our algorithms and make your widgets more efficient. If you do not want to display out-of-stock products in the widgets, import filters are just what you need.

Additional properties

You will likely not want to change the content of your feeds very often, however sometimes you will want to create advanced filters inside your widgets. Imagine you sell clothes and on product pages with blue pants you would like to only display other blue pants. Unfortunately in your feed you don't have any field called "Color". However you are pretty sure that the description always contains the color of the product.

To solve your problem, you would create a filter which creates a property called "bluepants", which would be true if the description contains the words "blue" and "pants" (in that order), and false otherwise.

Catalog additional properties

You would then use a filter such as this one in your widget configuration:

Catalog additional properties

This filter selects only "bluepants" products on product pages which are themselves tagged as "bluepants" by our additional properties tool.

Additional CSV data

Purchase history

In order to use fully personalized algorithms inside email widgets, it is necessary to upload a file containing users' purchase history. More information on creating personalized emails is available here.

What is needed is a text file containing the same unique identifiers for your customers as used by your email marketing tool (such as the email address), as well as their purchasing history. To illustrate, we will use a text file containing the purchasing history of two customers: example1@server.com and example2@server.com. The customer example1@server.com bought the products product1, product3, and product7. The customer example2@server.com bought only product2. A text file containing this data could look like this:

1
2
3
uselessdata;customer_email_address;product_ids
junk;example1@server.com;product1,product3,product7
more_junk;example2@server.com;product2

What is important is that there is one column containing the identifiers of your customers, and another containing their purchasing history, with comma-delimited product ids. On the page for your catalog settings, there is a section called "Upload additional CSV data". We will choose to "Upload "purchase history" data in CSV" by clicking on "Configure"

purchase history configure button

Next, we select the file, and upload it:

purchase history upload button

Once this is done, we need to provide some information to help TasteHit understand the format of the file containing the purchasing history. For our example, the correct configuration looks like this:

purchase history file parsing properties

We finish by clicking on "Launch file update". This will launch a job at TasteHit that will import your data into TasteHit's database. When this is done, you can start using personalized product selection algorithms.

In order to use the Compatible algorithm in a web widget, you need to provide TasteHit with a file containing compatibilities between products. TasteHit will automatically use the relationships defined in this file to display compatible products when the user lands on a product page from one of the products mentioned in the file.

Your "related products" file is a text file which needs to contain a compatibility between two products on each line. For example, if you have 3 products in your catalog (with Unique IDs "A", "B" and "C"), and that you want products "A" and "B", and "B" and "C" to be compatible, but not "A" and "C", you would need a file with the following content:

1
2
A;B
B;C

Once your "related products" file is ready, go to your catalog settings page catalog settings, in the "Upload additional CSV data". Click on the "Configure" button in the Upload "related products" data in CSV parameter:

related products setup button

A form will appear. This form helps TasteHit understand the format of your file. For the example above, the correct configuration would look like this:

related products upload form

Choose your file and click on Upload. A message will appear saying the upload was successful. Configure the CSV parameters and click on Launch file update. This will launch a job that will import your data into TasteHit's database. When this is done, you can start using personalized product selection algorithms. You can verify the timestamp by reloading the page.

Frequently asked

Import frequency

TasteHit will automatically update the catalog once a day. We cannot give a precise time as the update job depends on a number of internal factors. If you modified your catalog files and would like to run a feed import as soon as possible, simply click on the "Update now" button at the top of the page:

Catalog files

Internationalization

If your shop is available in several languages, there is nothing to worry about: TasteHit natively supports shops with multiple languages and locations at no additional cost. We import your catalog files in different languages and render product recommendation widgets according to parameters you define (typically URLs or domain names). This is further described in the CSV format section. The answer is the same if all your shops are available under different domains: as long as the Unique IDs of your products are the same on all your shops (even if their parameters such as title, price and availability are different) everything works as described in this section. If you have specific requirements, do not hesitate to contact us.

Supported CMSs

If you are using an installable CMS (Magento, Prestashop, WooCommerce, Hybris, Websphere), or a cloud-based CMS (DemandWare, Shopify, VTEX), or if you developped your own e-commerce site in any programming language, you will be able to use TasteHit. There is no reason why you would not be able to export a product feed. A product feed is simply an export of you product database into a file with the format and content you define yourself. Most CMS' provide extensions to export feeds in a standard format (Google Shopping, Shopzilla, standard CSV, etc...), and we support all those.

If you use Magento or Prestashop you can download the TasteHit Magento plugin and Prestashop add-on developed by our team directly from the following links: Magento plugin and Prestashop add-on.

If you cannot find a way to do this export, you could create, or ask a developer to create, a script (or CRON job) for you. The CRON jobs will simply do a periodic export of your database in CSV/XML/JSON format. If you have trouble with those, feel free to contact us.

Comments