Kameleoon

This is a premium feature. Please contact your Customer Success Manager to enable it on your Kameleoon Account.

There are three easy methods for syncing your product catalog into Kameleoon:

Via Kameleoon’s Product API. We recommend this method if you have a data layer that contains detailed information about your products and product categories. Working with our API requires that you have metadata available for products and categories from your product pages (i.e., in a data layer) that Kameleoon can read and feed into our product recommendation algorithms.
With an XML file containing all required metadata for each of your products. Use this method if you don’t have a data layer and you experience high volatility in your product stock or your product catalog has limited stock quantities (and, therefore, you need to refresh your product catalog frequently). You can easily choose the frequency Kameleoon should sync your catalog in the store settings page. We recommend doing an XML import once every 24-72 hours to update Kameleoon with your product stock.
Via Kameleoon’s REST API. Utilize Kameleoon’s REST API for updating your catalog if you need regular updates, especially when dealing with products that quickly go out of stock due to limited availability. We also recommend this approach if your product catalog exceeds 200K items or if your product feed size is over 300MB. Keep in mind that while the limitation (gzip compressed file) is set to 2GB, the larger your catalog, the longer it will take to process the feed, so we recommend opting for a syncronization of 6+ hours.

Note: Kameleoon will automatically mark all products not present in the feed as out of stock. Thus, to enhance the feed processing speed and reduce its size, we recommend excluding out-of-stock products from your feed.
It’s important to note that one drawback of the Product API method is that if products are not actively searched for or browsed by visitors, Kameleoon may not be aware of those products, and they may not be proposed in product recommendation blocks.

Syncing your Product Feed using Kameleoon Product API
Syncing your Product Feed using a XML file
Validate your feed sync status

Syncing your Product Feed using Kameleoon Product API

Kameleoon’s Product API powers our product recommendation algorithms as well as social proofing messaging, such as product impressions and purchases counters and advanced targeting conditions.

Once our Product API methods have been enabled on your website, Kameleoon will start sending product detail events whenever your visitors browse a product or category page, add a product to their carts, or make a purchase. It will also enable the collection of statistics about a given product (e.g., the number of times it was purchased or viewed in the last hour, or day) and power the creation of audience groups you can use in our segment builder using predefined product targeting criteria.

You’ll need to add our Product page, Category page, Cart page, and Thank you page snippets to your source code to track interactions with your products and inform our Product Recommendations algorithm. You can also inject them by using our Global custom script feature.

Product page

You need to use the method trackProductView. Read our detailed instructions.

It’s very important that you send the maximum of product attributes with this method to ensure our product algorithms can provide the most relevant recommendations. Read more

Category page

You need to use the method trackCategoryView. Read our detailed instructions.

Make sure that the category ID you use here matches the category ID sent with the trackProductView method. Read more

Cart page

You need to use the method trackAddToCart whenever a product has been added to the visitor’s cart or when the visitor accesses the cart page. Read our detailed instructions

Thank you page

You need to use the method trackTransaction whenever a purchase/transaction is done by a visitor. Read our detailed instructions

Note: Kameleoon syncs your whole product catalog every 2 hours and will automatically tag out of stock products as “unavailable” every 12 hours. A product is considered unavailable when the availableQuantity attribute passed with the addProductView method is equal to 0. This ensures that our product recommendations only include products that are in stock. You can also set a product to be out of stock using the availableQuantity attribute when using the addProductView method.

Syncing your Product Feed using a XML file

Syncing your product catalog using an XML file includes the following steps:

Create an XML file with all the required metadata for each of your products, categories, and locations (e.g., countries or locations where you operate and have different pricing, stock, or details for your products). The file needs to be available from a distant URL. Please be sure that you host it in a secure area (e.g., S3 bucket) that is accessible to Kameleoon.
Sync the XML file with Kameleoon and choose the update interval that suits your needs (e.g., every hour, 3 hours, 6 hours, etc.)
Track your visitors’ events.

Note: Multiple languages websites are not supported, you will need to create a separate project for each language and provide one feed for each.

Step 1: Creating your product feed

The product feed must include basic information about your catalog. Refer to the tables below for the mandatory attributes you must include.

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2022-10-03 22:00">
  <shop>
    <categories>
      <category id="270821163172" parentId="2708" url="https://myurl.com">Adidas</category>
       .......
    </categories>
    <offers>
      <offer id="6737859641508" available="true" leftovers="lot"></offer>
      ......	
    </offers>
   </shop>
</yml_catalog>

Element : yml_catalog

Attribute	Mandatory	Description
date	Yes	Date of generation of the XML document. Format should be : YYYY-MM-DD hh:mm

Element : yml_catalog > shop

Element	Mandatory	Description
categories	Yes	List of store categories
locations	No	List of locations / countries where the store is represented
offers	Yes	List of store products

Element : yml_catalog > shop > categories

The categories element contains a list of category elements. Each product category you use to group or tag your products is described by a separate category element.

Attribute	Mandatory	Description
id	Yes	Category ID
parentId	No	Parent category ID
url	No	Link to category page
alias	No	The alias identifier of the category

Example:

<categories>
  <category id="2" url="http://my-store.com/categories/discount/"> Category level 1</category>
  <category id="8" url="http://my-store.com/categories/men/">Category level 1</category>
  <category id="13" parentId="8" url="http://my-store.com/categories/men/shoes/">Category level 2</category>
  <category id="97" parentId="13" alias="men/shoes/leather" url="http://my-store.com/categories/men/shoes/leather">Category level 3</category>
</categories>

Element : yml_catalog > shop > locations

The locations element contains a list of your store locations. Each location is described by a separate location element.

You can use the following attributes for the element locations:

Attribute	Mandatory	Description
id	Yes	Location ID
parentId	No	Parent location ID
type	No	Location type. Available values: state, city, store
name	No	Location name

Example:

<locations>
   <location id="1" type="city" name="New York" />
   <location id="2" type="city" name="Los Angeles" />
   <location id="145" parentId="1" type="store" name="New York City main store" />
</locations>

Element : yml_catalog > shop > offers

The offers element contains your list of products. Each product is described by a separate offer element.

Note: If all variants of one product are available from the same URL in your store, and there is no common identifier for product variants, Kameleoon will choose the cheapest product variant when recommending this product to your visitors. The availability flag in this case should fit into the following logic: if at least one product variant is in stock, then the product is considered in stock.

Element : yml_catalog > shop > offers > offer

You can use the following attributes for the offer element:

Attribute	Mandatory	Description
id	Yes	Product ID / SKU / EAN
group_id	No	Product group ID. Required to combine product variants into one group. Kameleoon will choose the cheapest variant when recommending this product to visitors
available	Yes	Indication whether the product is in stock (‘true/false’). Note: Kameleoon will automatically make all products that are not in the feed out of stock. Therefore, to speed up feed processing and reduce its size, we recommend not adding products that are out of stock in your feed.
leftovers	No	Indication of how much inventory of a particular product is available. It can take one of the following values: one (the product is available in a single copy), few (the product is in limited quantities – up to 10 units), lot (available from 10+ units of the product)

The offer element can take the following tags:

Element	Mandatory	Description
name	Yes	Product Name
picture	Yes	Product main image
price	Yes	Base price of the product
url	Yes	URL to the product details page (starting with HTTP/HTTPS)
categoryId	Yes	Product category. If the product is associated with several categories, add as many `categoryId` elements as needed
locations	No	Required if the properties of the product (price, availability) are different depending on your locations. See table and example below
accessories	No	List of products that can be complementary or equivalent to the current product. It allows you to recommend products that can be used in combination with the current product (or in replacement of). It is usually needed for a fashion or auto store and this tag is only compatible with the Store Recommendations algorithm.
oldprice	No	The previous price of the item. Used to show the product discounted price in product recommendation blocks.
price_margin	No	A weighting factor of the product price margin, between 0 and 100. Used to show products that have a higher margin in product recommendation blocks.
barcode	No	Product barcode or SKU. Used for our search algorithms.
typePrefix	No	Product type (eg. “mobile phone”, “washing machine”, “corner sofa”). Used for our search algorithms.
vendor	No	Manufacturer/brand
vendorCode	No	The manufacturer / brand’s code. Used for our search algorithms.
model	No	Model and product name (eg. Iphone 14 128GB). Used for our search algorithms.
seasonality	No	Seasonality of goods. Allows you to recommend this product only some months of the year. Add as many elements as needed. See example below
is_new	No	Must be “1” if the product is new. Required if you use the algorithm “New arrivals”
rating	No	Product rating. Must take a value from 0 to 5. Must be 0 if the product has no rating
description	No	Product description
stock_quantity	No	Indication of the product stock quantity
tags	No	Any additional information describing the product. Used for our search algorithms. You can add a maximum of 5 tags. See table and example below
param	No	Used to provide filtering options in the search listing page provided by Kameleoon. Add as many param elements as needed. See example below
author	No	Only required if you sell books online
publisher	No	Only required if you sell books online
series	No	Only required if you sell books online
year	No	Only required if you sell books online
ISBN	No	Only required if you sell books online

Example:

<accessories>
    <accessory id="5574" />
    <accessory id="131" />
    <accessory id="99444" />
    <accessory id="334411" />
</accessories>

Element : yml_catalog > shop > offers > offer > locations

The locations element contains a list of locations, as well as the availability and price of the current product in these locations. Each location is described by a separate element location within the offer tag.

You can use the following attributes for the locations element:

Attribute	Mandatory	Description
id	Yes	ID of the location where the product is currently listed. Must be one ID from one of the locations elements in the Shop element (see section above). Add as many elements as needed

Note: The product will only be considered available for purchase in those locations that are listed in the offer element. In all other unlisted locations, the product will be considered out of stock. You don’t need to add locations if your product is available in all locations, as Kameleoon will automatically consider the product in-stock in all of them.

The locations element can take the following tags (only required if the product has a different price / stock quantity in some of your locations).

Element	Mandatory	Description
price	No	The price of the product in the listed location
oldprice	No	The previous price of the product in the location
stock_quantity	No	Product stock quantity in the location

Element : yml_catalog > shop > offers > offer > fashion

Use the fashion tag if you sell clothes products.

The fashion element can take the following tags:

Element	Mandatory	Description
gender	no	Product gender Must be “f” (Female) or “m” (Male)
type	no	Product type See table below for the allowed values
sizes	no	Product available sizes See table below for the allowed values
color	no	Product color See example below
feature	no	Product specificities Use this element to indicate if the product is for adults or kids only. Must take the value “child” or “adult”.

Note: If the product does not belong to a specific gender, do not specify the gender element. In this case, the product will be rated “unisex” and will have a lower recommendation priority than other products of the same gender.

The type element can take the following values:

Element value (gender)	Description
shoe	Shoes
shirt	Shirts, blouses, dresses
tshirt	t-shirts
underwear	Underwear
trouser	Pants, jeans, shorts, skirts, swimwear
jacket	Jackets, coats, fur coats
blazer	Jackets, vests, jumpers
sock	Socks
belt	Belts
hat	Hats
glove	Gloves

Example:

<offer ...>
    ...
    <fashion>
        <gender>f</gender>
        <type>shoe</type>
    </fashion>
</offer>

Note: The type parameter is required when using the sizes parameter. You can add a list of available sizes by adding as many size tags as needed within the sizes element (see example below).If you have several locations, and the availability of product sizes is different across locations, insert a location tag with the list of available sizes in each size element (see example below).

Description	Example
European size	e38
International size	M, L, u30
UK size	b6
Height (for children’s products)	h89-95
One size fits all	null

Example:

<offer ...>
    ...
    <fashion>
        <gender>f</gender>
        <type>shoe</type>
        <feature>adult</type>
        <sizes>
            <size>e41</size>
            <size>e42</size>
            <size>e44</size>
            <size>e48</size>
        </sizes>
    </fashion>
</offer>
<offer ...>
    ...
    <fashion>
        <gender>m</gender>
        <type>jacket</type>
        <sizes>
            <size value="M">
              <location id="3"/>
            </size>
        </sizes>
    </fashion>
</offer>

Note: One product can have multiple colors available. You can set a specific picture for a color by adding a picture attribute. Otherwise, the main picture will be displayed.

Example:

<offer ...>
    ...
    <fashion>
        <gender>f</gender>
        <type>shirt</type>
        <color>white</color>
        <color picture="https://example.com/products/shirts/395532-blue.jpg">blue</color>
    </fashion>
</offer>

Element : yml_catalog > shop > offers > offer > auto

Use the auto tag if you sell auto parts and accessories. Our algorithm is designed to automatically recognize a potential buyer with certain characteristics, like the brand and model of the car. It will be used to display parts and accessories in recommendation blocks that are only compatible with specific car brands and models.

The auto element contains a list of compatible cars. Each car brand and model is described by a separate compatibility element.

Note: If the product is compatible with all cars, you do not need to add compatibility elements. If the product is compatible with all car models of a brand, the attribute model does not need to be added.

You can use the following attributes for the element compatibility:

Attribute	Mandatory	Description
brand	Yes	Car brand
model	No	Car model

If the product is only compatible with a list of cars, you can also add a vds element for each compatible car. The vds contains the Vehicle Identification Number (VIN) that serves as the car’s fingerprint.

Example:

<offer ...>
    ...
    <auto>
        <compatibility brand="BMW" />
        <compatibility brand="Mini" model="Cooper S" />
        <compatibility brand="Mini" model="Cooper C" />
        <vds>BP8AN5</vds>
        <vds>BP8AN5</vds>
    </auto>
</offer>

Element : yml_catalog > shop > offers > offer > tags

The tags element contains a list of tags associated with the product. This is useful for improving Kameleoon’s search engine recommendation. Each value is described by a separate tag element.

Element	Mandatory	Description
tag	Yes	Tag value

You will find below examples of XML files you can use as a template:

XML product feed – example 1 (without locations elements):

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2022-10-03 22:00">
	<shop>
		<categories>
			<category id="270821163172" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/adidas">Adidas</category>
			<category id="270821261476" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/asics">Asics</category>
			<category id="270821228708" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/converse">Converse</category>
			<category id="270821425316" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/drmartens">Dr Martens</category>
			<category id="270821490852" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/flex">Flex</category>
			<category id="2708211" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/trainers">Sneakers</category>
			<category id="2708" url="https://kameleoon-store.myshopify.com/collections/all">Shoes</category>
		</categories>
		<offers>
			<offer id="6737859641508" available="true" leftovers="lot">
				<url>https://kameleoon-store.myshopify.com/products/adidas-kids-stan-smith</url>
				<price>50.99</price>
				<oldprice>90</oldprice>
				<price_margin>45</price_margin>
				<categoryId>270821163172</categoryId>
				<categoryId>2708211</categoryId>
				<picture>https://cdn.shopify.com/s/files/1/0564/9180/2788/products/7883dc186e15bf29dad696e1e989e914_grande.jpg?v=1622707556</picture>
				<name>ADIDAS | KID'S STAN SMITH</name>
				<is_new>1</is_new>
				<rating>4</rating>
				<vendor>Adidas</vendor>
				<description>The Stan Smith owned the tennis court in the '70s. Today it runs the streets with the same clean, classic style. These kids' shoes preserve the iconic look of the original, made in leather with punched 3-Stripes, heel and tongue logos and lightweight step-in cushioning. </description>
				<stock_quantity>300</stock_quantity>
				<tags>
					<tag>Sneakers</tag>
					<tag>Lean low top sneakers</tag>
					<tag>Men sneakers</tag>
				</tags>
				<fashion>
					<type>shoe</type>
					<color>black</color>
					<sizes>
						<size>9</size>
					</sizes>
					<feature>child</feature>
				</fashion>
				<param name="Size" unit="EU">9</param>
				<param name="Color">white</param>
			</offer>
			<offer id="6737859641509" available="false">
			......
			</offer>	
		</offers>
	</shop>
</yml_catalog>

XML product feed – example 2 (with locations elements):

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2022-10-03 22:00">
	<shop>
		<categories>
			<category id="270821163172" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/adidas">Adidas</category>
			<category id="270821261476" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/asics">Asics</category>
			<category id="270821228708" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/converse">Converse</category>
			<category id="270821425316" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/drmartens">Dr Martens</category>
			<category id="270821490852" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/flex">Flex</category>
			<category id="2708211" parentId="2708" url="https://kameleoon-store.myshopify.com/collections/trainers">Sneakers</category>
			<category id="2708" url="https://kameleoon-store.myshopify.com/collections/all">Shoes</category>
		</categories>		
		<locations>
			<location id="1" type="city" name="New York" />
			<location id="2" type="city" name="Los Angeles" />
			<location id="145" parentId="1" type="store" name="New York City main store" />
		</locations>		
		<offers>
			<offer id="6737859641508" available="true" leftovers="lot">
				<url>https://kameleoon-store.myshopify.com/products/adidas-kids-stan-smith</url>
				<price>50.99</price>
				<oldprice>90</oldprice>
				<categoryId>270821163172</categoryId>
				<categoryId>2708211</categoryId>
				<picture>https://cdn.shopify.com/s/files/1/0564/9180/2788/products/7883dc186e15bf29dad696e1e989e914_grande.jpg?v=1622707556</picture>
				<name>ADIDAS | KID'S STAN SMITH</name>
				<is_new>1</is_new>
				<rating>4</rating>
				<vendor>Adidas</vendor>
				<description>The Stan Smith owned the tennis court in the '70s. Today it runs the streets with the same clean, classic style. These kids' shoes preserve the iconic look of the original, made in leather with punched 3-Stripes, heel and tongue logos and lightweight step-in cushioning. </description>
				<stock_quantity>300</stock_quantity>
				<tags>
					<tag>Sneakers</tag>
					<tag>Men</tag>
				</tags>
				<locations>
					<location id="145">
						<price>63</price>
						<oldprice>90</oldprice>
						<stock_quantity>90</stock_quantity>
					</location>
				</location>
				<customerRecommendations>67378596415,673785964150821,673785964150,673785964150811</customerRecommendations>
			</offer>
			<offer id="6737859641509" available="false">
				......
			</offer>	
		</offers>
	</shop>
</yml_catalog>

Step 2: Sync your product feed file with Kameleoon

By default, the Kameleoon feed syncs with your XML file every 24 hours. However, you can change this setting if your product catalog updates more frequently. You can make adjustments in the Store Settings.

Step 3: Track visitors’ events

In addition to syncing your XML product feed, you need to implement events to track product events, such as product view, add to cart, and transaction.

Product views

You need to use the trackProductView method.

Kameleoon.API.Products.trackProductView("ProductID/SKU/EAN");

Read our detailed instructions

Add to cart

You need to use the trackAddToCart method whenever a product has been added to the visitor’s cart or when the visitor accesses the cart page.

Kameleoon.API.Products.trackAddToCart("ProductID/SKU/EAN");

Read our detailed instructions

Transaction

Kameleoon.API.Products.trackTransaction([
	{
	 "productID": "ProductID/SKU/EAN 1",
	 "quantity": 1
	}
]);

Read our detailed instructions

Validate your feed sync status

If you use our Product API, you can verify that your implementation was successful at any time by using the obtainProductData method. This allows you to easily QA your implementation in real-time and verify that Kameleeon collected your product attributes correctly.

You can visualize your product catalog by using the Product feed entry menu.