full integration documentation

Don’t want to write any code? Learn about our worry-free integration.

1.1 Widget

Copy the following code to the bottom of the tag of your shop template, and fill in the parameters.

<script type="text/javascript">
 $('#fitanalytics-size-advisor').hide(); /* hide the size advisor link until
                                            the product data get loaded */
 window._fitAnalytics = function() {
   var widget = new FitAnalyticsWidget({
     productSerial: "yourshopname-abcd123456",
     thumb: "http://yourshopname.com/images/garment.jpg",
     manufacturedSizes: {"S": true, "M": false, "L": true}, // size M is out-of-stock, while sizes S and L are in-stock
     load: function(productSerial) {
        $('#existing-size-chart').hide();
        $('#fitanalytics-size-advisor').bind('click', function() {
              widget.open();
              return false;
        });
        $('#fitanalytics-size-advisor').show(); /* product data were loaded, so the
                                                   size advisor link can be displayed */
     }
   });
 };
</script>
<script type="text/javascript" src="//widget.fitanalytics.com/widget.js"></script>

Details

productSerial - product ID for Fit Analytics, usually in the form of <shopname>-<article_id>

The productSerial tells the widget for which garment it should load the fit prediction. It is the most important parameter, upon which all others depend.

thumb - absolute URL to a product image thumbnail. Thumbnail image dimensions should be at least 300 x 300 pixels for optimal appearance.

The optional thumb parameter allows you to override the thumbnail we have stored for your garment (if any) with a custom image. You need to pass an absolute URL for this and it should be an image that is at least 300 x 300 pixels.

manufacturedSizes - a JavaScript object that list all in-stock and out-of-stock sizes of the specified product

The manufacturedSizes parameter is also optional and allows you to pass a list of sizes for that specific garment to the widget. This allows Fit Finder to treat in-stock sizes different from out-of-stock sizes. For example, only in-stock can be added to cart through Fit Finder. The listed sizes must be in the same format as the sizes shown on the product page.

load - a callback that is executed once the widget loads the product information

The load function is called when the widget has successfully loaded the product data associated with the productSerial — in other words, when the widget has the relevant data and is ready to be opened by the user. Therefore, when implemented as shown in the above code example, the load callback enables the following behaviors:

  • Hides the fallback existing-size-chart linking element.
  • Binds “click” on the fitanalytics-size-advisor element, so that widget.open() is called when the user clicks on the element.
  • Shows the fitanalytics-size-advisor element, which would typically be hidden until the product data loads.

We strongly recommend using the callback function code to make the widget link visible. By doing so, the widget will be available for use only for products that are supported by Fit Analytics. This enables an easy and dynamic integration where the widget code is included in every product page, but the widget link is hidden for unsupported products.

The callback function receives the productSerial as its only parameter.

1.2 Product Feed

Please provide us with your product feed so that we can perform automatic updates to our database. We prefer— but do not require— csv format. If you already maintain a product feed for another purpose, we can most often work with this existing version so long as it contains the following garment information.

The following fields are required for basic Fit Finder support:

  • product ID (often called “SKU”): A number or code that uniquely identifies the product (independent of clothing size). This ID is part of the productSerial parameter used in the widget integration code (productSerial = <shopname>-<product_id>). This ID varies with color.
  • brand (often called “manufacturer” or “designer”): The product’s brand (e.g. Esprit or Diesel).
  • category path: Something that allows us to distinguish supported products (e.g. shirts, pullovers, dresses, skirts) from unsupported products (e.g. hats, belts).
  • gender: The gender for which the product is intended, e.g. “men” or “women” (only required if both men’s and women’s clothing is sold).
  • age group: If the gender column does not distinguish adults from children, an age group column is required (e.g. “adults“, “kids“, “toddlers“).
  • size: For each product in the feed, there should be several rows that specify the sizes in which the product is manufactured (e.g. “S“, “M“, “L“, “XL“). The product feed should ideally include both in-stock and out-of-stock sizes.

The following fields are required for advanced Fit Finder support and Fit Connect support:

  • style ID: A number or code the identifies the style of the product. All size / color variants of the garment will have the same style ID.
  • thumbnail URL: A link to a thumbnail (preferably at least 300x300 pixels) of the product.
  • Link to Product Page (deeplink): A link to a the actual product details page.
  • product title: A short description of the product that is suitable for display in the Fit Finder (e.g. "Diamond-Patterned Stretch Cotton Pants").
  • stock / quantity: Indicates whether the size is currently in-stock or out-of-stock. If the size is in-stock, specifying the stock level is ideal.

The following fields are very helpful for optimizing Fit Finder and Fit Connect performance:

  • EAN (or UPC or GTIN): Including the barcode(s) for the product helps us tie it to existing data.
  • Article Code: A shop-specific ID that uniquly identifies the product and size. Each product ID will have several article codes associated with it (one article code per size).
  • Fit / Cut: A brief description of the fit (e.g. “slim”, “relaxed”, “regular”).
  • Product Line: If a brand has several lines, the product line should be specified (e.g. Zara TRF, H&M L.O.G.G, Boss Orange).
  • Color: The color of the product (e.g. “White”, “Marine Blue”, “Red”).
  • Style Name: The style name (e.g. “501”, “Arizona”, “Larkee”, “Mark”, “Air Max”).
  • Swatch Image Link: A link to a a close-up image of the product.
  • [Pants] Rise: Optional and relevant for pants only; specifies the rise (e.g. “low rise”).

There are additional fields that are helpful, but not required. Please contact your Fit Analytics Project Manager for a sample product feed.

2.1 Customization

Fit Finder is readily-customizable to support your visual brand guidelines. To customize your Fit Finder, simply provide us with the following assets:

  • A logo file (to be delivered in any standard graphics format)
  • A custom brand color (to be specified as a six-digit hexidecimal value). Note: this can be any color associated with your store’s brand, so long as white text can appear legibly on top of it— we’ll notify you if we anticipate any problem with the custom color value you provide.

Once we receive these assets from you, your logo will appear in the top right corner of the widget and your custom color will be used for buttons and specific graphical elements.

2.2 Add to cart

Fit Finder allows your customers to add the recommended size (or any other size) to the shop's cart directly from within the widget. Adding the Add-to-cart feature to Fit Finder can be done by inserting the cart callback parameter into the integration code.

cart: function(productSerial, size) { /* add size to shopping cart */ }

The callback function is called when the user clicks on the “Add to cart” button in the widget. The button is only visible if the cart callback function is defined, otherwise it is replaced with a “Return to store” button. The size parameter will always contain the currently selected size from the widget as a string. For example, if the user selects size “M” in the widget and then clicks the “Add to cart” button, the widget will close and the “cart” callback will be executed with the size parameter “M”. In case both cart and close are defined as callbacks, only the cart callback will be executed when the user clicks on the “Add to cart” button.

2.3 Immediate recommendation

If the user has already entered his details during the current session and received a size recommendation (e.g. on another product page), it is possible for him to receive a size recommendation for additional products without opening the widget. This feature allows the user to see his recommended size directly on the product page, without requiring him to re-open the Size Advisor.

To enable this behavior, the integration code must include:

  • a call to widget.getRecommendation(), which uses his previously-entered data to retrieve an immediate size recommendation, which is then passed as a parameter to the “recommend” callback.
  • the recommend callback, which receives three possible values:
    • “new user” - the user’s measurements data are not complete, and therefore the widget cannot recommend a size yet.
    • a size recommendation in the relevant format, for example: “M” or “40”.
    • “error” - there was an error in the data.

Please see below an example that includes the immediate recommendation feature as well as the add-to-cart feature.

<script type="text/javascript">
 $('#fitanalytics-size-advisor').hide(); /* hide the size advisor link until
                                             the product data get loaded */
 window._fitAnalytics = function() {
   var widget = new FitAnalyticsWidget({
     productSerial: "yourshopname-abcd123456",
     thumb: "http://yourshopname.com/images/garment.jpg",
     manufacturedSizes: {"S": true, "M": false, "L": true}, // size M is out-of-stock, while sizes S and L are in-stock
     cart: function(productSerial, size)       { /* add size to shopping cart */ },
     recommend: function(productSerial, size)  { /* get immediate size recommendation */ }
     load: function(productSerial) {
        widget.getRecommendation();
        $('#existing-size-chart').hide();
        $('#fitanalytics-size-advisor').bind('click', function() {
              widget.open();
              return false;
        });
        $('#fitanalytics-size-advisor').show(); /* product data were loaded, so the
                                                   size advisor link can be displayed */ 
     }
   });
 };
</script>
<script type="text/javascript" src="//widget.fitanalytics.com/widget.js"></script>

2.4 Prefilling

If you already know some or all of the basic info that we need from the user to give an accurate fit prediction (for example, in an instance where the user already entered his data into your shop system), you can prefill the form on the initial widget screen by passing in these parameters:

<script type="text/javascript">
 window._fitAnalytics = function() {
   var widget = new FitAnalyticsWidget({
     productSerial: "yourshopname-abcd123456",
     userAge: "28",      // age of the user
     userGender: "w",    // gender, "m" for male or "w" for female
     userWeight: "80",   // weight in kilograms
     userHeight: "180",  // height in centimeters
     userBraBust: "75",  // bra bust, only relevant for female users
     userBraCup: "B",    // bra cup size, only relevant for female users
     userBraSystem: "EU" // bra system, can be: EU,UK,US,AU,NZ,BR
     /* more parameters and widget open code here ... */
   });
 };
</script>
<script type="text/javascript" src="//widget.fitanalytics.com/widget.js"></script>

userAge / userGender / userWeight / userHeight

These parameters prefill the basic form fields with the passed values. They are all optional - if any of them is missing then the associated form fields will be left empty. The gender needs to be passed as either lowercase “m” for male or lowercase “w” for female; any other value will not be recognized. Height and weight need to be passed in metric units, which means centimeters for the height and kilograms for the weight. In case you have inches or lbs, you need to convert the data before passing it to the widget.

userBraCup / userBraBust / userBraSystem

In case the user is female, we also need to know her bra size. To prefill the bra dropdowns, you can use these parameters. They are optional as well; depending on the bra system it might not be necessary to prefill userBraCup, for example. The currently supported bra systems are “EU”, “UK”, “US”, “AU”, “NZ”, “BE”, “ES”, “FR”, “IT”, “CZ” and “BR” (which won’t need bra cup) and you should pass them along with any bra values, because the widget would otherwise try to automatically determine the right one and might pick one that does not allow the other bra values you sent.

2.5 Localization

Sometimes it might be necessary to manually set a specific property of the widget, because it should be in a specific language, sizes region or units system. For this purpose, there are several parameters that allow you to force the Fit Analytics widget to ignore automated routines or stored data and deliver an experience that’s exactly how you want it to be:

<script type="text/javascript">
 window._fitAnalytics = function() {
   var widget = new FitAnalyticsWidget({
     productSerial: "yourshopname-abcd123456",
     language: "de",    // always show the widget in German
     shopCountry: "AT", // Austrian version of the shop
     metric: 1          // enforce metric system
     /* more parameters and widget open code here ... */
   });
 };
</script>
<script type="text/javascript" src="//widget.fitanalytics.com/widget.js"></script>

language: en / de / fr / es / it / ru / nl / fi / tr / ro / pl / sv ...

This parameter manually forces the widget to be delivered in the specified 2-letter language (ISO 639-1), for example “en” for English, “de” for German, “fr” for French or “pt” for Portuguese.

shopCountry: US / GB / DE / FR / AT / CH / ES / IL / BR / RU / NL / FI / IT / CN ...

If your shop is available in multiple countries, this parameter allows you to customize the Fit Finder experience to the current shop's country (e.g. display the relevant flag). Moreover, sometimes you want to offer the same products with more than one set of sizes, based on the language/country of your shop, or any other criteria.
In that case, the country parameter will be used to select the correct sizing system of the product. Important note: certain language and country combinations are blocked, as they may lead to ambiguous sizing systems. For those combinations, Fit Finder will not open.

metric: 0 / 1 / 2

Usually, we are able to determine whether imperial or metric system should be used in the widget based on geographic location. In cases when we are not able to make this determination, the measurement system is selected according to the browser’s language. This selection can be incorrect at times, so if you want to pre-select either the metric or the imperial unit system, you can pass this parameter with a value of 1 for the metric units system or a value of 0 for the imperial units system. Passing the metric parameter with a value of 2, will set the widget to use the imperial system, but with stones instead of pounds as weight units.

3.1 Overview

In many cases, it is useful for your shop to share its sales data with Fit Analytics — for example, in the case of a Pay-Per-Purchase model, namely, when your shop pays a fee to Fit Analytics only for items that were purchased by a user after getting a size recommendation via the Fit Analytics widget.

Sharing your sales data is done in two steps:

1) Sharing purchase data

Sharing your purchase data with Fit Analytics is done in real time by embedding Javascript code in the order confirmation page.

2) Sharing return data

Sharing your return data is ideally done by sending Fit Analytics aggregated return data periodically. Fit Analytics can parse and analyze extracts from your sales database. Normally, the data are shared with Fit Analytics via a link to a CSV file that contains records for an agreed-upon period of time.

Required fields

Ideally the data should contain the following information per purchase/return. Please note that the last two are relevant only for returns.

  • order id: an id of the order.
  • user id: relevant if your shop uses an id for users across multiple sessions.
  • time stamp: the time at the moment of purchase.
  • product serial: the same identifier that you sent to the widget via the productSerial parameter.
  • shop article code: a size-specific identifier if it exists (for example, if a product is sold in 5 sizes, there would be 5 shop article codes mapping to one product serial).
  • ean: a 13-digits universal barcode that identifies the product and size (EAN in wikipedia).
  • purchased size: the purchased size.
  • shop country: if your shop has country-specific versions, you can specify the shop's country in which the purchase was made.
  • language: if your shop has language-specific versions, you can specify the language in which the purchase was made (which helps identify the user's sizing system)
  • price: price of the purchased item (please note that we use ISO 4217 for specifying the currency).
  • returned: whether the item was returned.
  • reason: if known, reason for return ‒ ‘big’ if the size was too big, ‘small’ if the size was too small, ‘fit’ if it was another fit-related problem, or ‘other’ if the reason was not related to fit (color, for example).

Please see a detailed code example in the below paragraph.

3.2 Purchases

In order to report purchases, use the _sendPurchaseInformation() function. Simply edit the following example and embed it in your order confirmation page:

<script type="text/javascript">
 window._fitAnalyticsReportPurchase = function() {

   window._sendPurchaseInformation({
     productSerial: "yourshopname-abcd123456",
     shopArticleCode: "2523818691",
     ean: "0889516928738",
     orderId: "xyz123",
     userId: "4512345gfh",
     purchasedSize: "48",
     shopCountry: "CH",
     language: "de",
     price: 21.98,
     currency: "EUR"
   });

   window._sendPurchaseInformation({
     productSerial: "yourshopname-gdks652544",
     shopArticleCode: "7823418631",
     ean: "8719111842721",
     orderId: "xyz123",
     userId: "4512345gfh",
     purchasedSize: "M",
     shopCountry: "NL",
     language: "nl",
     price: 37.18,
     currency: "EUR"
   });

 };
</script>
<script type="text/javascript" src="//collector.fitanalytics.com/report_purchase.js"></script>

If you would like to use an AMD-compatible version of the purchases reporter, the script can export the Reporter object as an anonymously defined module. Please note that report_purchase_amd.js is used instead of report_purchase.js.

<script type="text/javascript">
  require(['//collector.fitanalytics.com/report_purchase_amd.js'], function (Reporter) {
    Reporter.sendPurchaseInformation({
      productSerial: "yourshopname-abcd123456",
      shopArticleCode: "2523818691",
      ean: "1717210104038",
      orderId: "avsdf3223",
      userId: "ad45s123gh",
      purchasedSize: "48",
      shopCountry: "GB",
      language: "en",
      price: 17.99,
      currency: "GBP"
    });

    Reporter.sendPurchaseInformation({
      productSerial: "yourshopname-gdks652544",
      shopArticleCode: "7823418631",
      ean: "1659510304035",
      orderId: "xyz123",
      userId: "4512345gfh",
      purchasedSize: "M",
      shopCountry: "US",
      language: "en",
      price: 42.00,
      currency: "USD"
    });
  });
</script>

4.1 How It Works

When the widget code from widget.js is loaded, two things happen:

  • a global class called FitAnalyticsWidget is created, which contains the whole widget logic and exposes several methods, of which open(), close() and getRecommendation() are the most relevant
  • after defining the global widget class, the JavaScript tries to execute the _fitAnalytics function that initializes the widget with all parameters and binds any events to the appropriate widget methods

To bind an HTML button on your shop page to the Fit Analytics widget, you have to modify the example code under the load parameter, so that whenever a user clicks on the button, widget.open() gets called. You also have to make sure that this binding happens inside the _fitAnalytics function, as the widget won’t be available outside of its context.

4.2 Compatibility

Fit Finder supports all major browsers. It loads jQuery 1.8.3 in noConflict mode, unless there is already a jQuery library with version 1.7 or newer present. To avoid version conflicts with different jQuery libraries, please make sure to run any critical code that relies on older jQuery versions before loading the widget code.

4.3 List of Callbacks and Events

An example with all possible parameters can be found below.

<script type="text/javascript">
 $('#fitanalytics-size-advisor').hide(); /* hide the size advisor link until
                                             the product data get loaded */
 window._fitAnalytics = function() {
   var widget = new FitAnalyticsWidget({
     productSerial: "yourshopname-abcd123456",
     thumb: "http://yourshopname.com/images/garment.jpg",
     manufacturedSizes: {"S": true, "M": false, "L": true}, // size M is out-of-stock, while sizes S and L are in-stock
     userId: "4512345gfh",  // the shop's user id, for example in case the user is logged in
     language: "de",        // load the widget in German
     shopCountry: "AT",     // Austrian version of the shop
     metric: 1,             // enforce metric system
     close: function(productSerial, size)      { /* do something on close */ },
     error: function(productSerial)            { /* do something on error */ },
     cart: function(productSerial, size)       { /* add size to shopping cart */ },
     recommend: function(productSerial, size)  { /* get immediate size recommendation */ },
     load: function(productSerial) {
        widget.getRecommendation();
        $('#existing-size-chart').hide();
        $('#fitanalytics-size-advisor').bind('click', function() {
              widget.open();
              return false;
        });
        $('#fitanalytics-size-advisor').show(); /* product data were loaded, so the
                                                   size advisor link can be displayed */ 
     }
     userAge: "28",         // age of the user
     userGender: "w",       // gender, "m" for male or "w" for female
     userWeight: "80",      // weight in kilograms
     userHeight: "180",     // height in centimeters
     userBraBust: "75",     // bra bust, only relevant for female users
     userBraCup: "B",       // bra cup size, only relevant for female users
     userBraSystem: "EU"    // bra system, can be: EU,UK,US,AU,NZ,BR
   });
 };
</script>
<script type="text/javascript" src="//widget.fitanalytics.com/widget.js"></script>

Details

1) productSerial:

Product ID for Fit Analytics, usually in the form of <shopname>-<article_id>. The productSerial tells the widget for which garment it should load the fit prediction. It is the most important parameter, upon which all others depend.

2) thumb (optional):

Absolute URL to a product image thumbnail. Thumbnail image dimensions should be at least 300 x 300 pixels for optimal appearance. The optional thumb parameter allows you to override the thumbnail we have stored for your garment (if any) with a custom image. You need to pass an absolute URL for this and it should be an image that is at least 300 x 300 pixels.

3) manufacturedSizes:

The manufacturedSizes parameter is also optional and allows you to pass a list of sizes for that specific garment to the widget. This allows Fit Finder to treat in-stock sizes different from out-of-stock sizes. For example, only in-stock can be added to cart through Fit Finder. The listed sizes must be in the same format as the sizes shown on the product page.

4) load:

A callback that is executed once the widget loads the product information. The load function is called when the widget has successfully loaded the product data associated with the productSerial — in other words, when the widget has the relevant data and is ready to be opened by the user.

5) close:

This function is called when the widget is closed by the user. It receives the productSerial as the first parameter and, depending on the screen the user was on, the currently selected size as the second parameter (or undefined, if the user didn’t get a size recommendation yet). Note that this callback will not be executed if the user closes the widget through the “Add to cart” button and triggers the cart callback.

6) cart:

This function is called when the user clicks on the “Add to cart” button in the widget. The button is only visible if the cart callback function is defined, otherwise it is replaced with a “Return to store” button. The size parameter will always contain the currently selected size from the widget as a string. For example, if the user selects size “M” in the widget and then clicks the “Add to cart” button, the widget will close and the cart callback will be executed with the size parameter “M”. In case both cart and close are defined as callbacks, only the cart callback will be executed when the user clicks on the “Add to cart” button.

7) error:

This function is called when loading the data failed, for example because the product associated with productSerial is not supported. It receives the productSerial as the first parameter.

8) recommend:

This function is called when the size recommendation data is retrieved, after calling widget.getRecommendation() (please see Immediate Recommendation section below). Once the size recommendation data is available, the recommend callback will be executed with the size parameter. The size parameter will always be of type string, and the following are the possible size values: “new user” - the user’s measurements data is not complete, and therefore the widget cannot recommend a size yet. a size recommendation - in the relevant format, for example: “M” or “40”. “error” - there was an error in the data.

9) language: en / de / fr / es / it / ru / nl / fi / tr / ro / pl / sv ...

This parameter manually forces the widget to be delivered in the specified 2-letter language (ISO 639-1), for example “en” for English, “de” for German, “fr” for French or “pt” for Portuguese.

10) shopCountry: US / GB / DE / FR / AT / CH / ES / IL / BR / RU / NL / FI / IT / CN ...

If your shop is available in multiple countries, this parameter allows you to customize the Fit Finder experience to the current shop's country (e.g. display the relevant flag). Moreover, sometimes you want to offer the same products with more than one set of sizes, based on the language/country of your shop, or any other criteria. In that case, the country parameter will be used to select the correct sizing system of the product.
Important note: certain language and country combinations are blocked, as they may lead to ambiguous sizing systems. For those combinations, Fit Finder will not open.

11) metric: 0 / 1 / 2

Usually, we are able to determine whether imperial or metric system should be used in the widget based on geographic location. In cases when we are not able to make this determination, the measurement system is selected according to the browser’s language. This selection can be incorrect at times, so if you want to pre-select either the metric or the imperial unit system, you can pass this parameter with a value of 1 for the metric units system or a value of 0 for the imperial units system. Passing the metric parameter with a value of 2, will set the widget to use the imperial system, but with stones instead of pounds as weight units.

12) userAge / userGender / userWeight / userHeight

These parameters prefill the basic form fields with the passed values. They are all optional - if any of them is missing then the associated form fields will be left empty. The gender needs to be passed as either lowercase “m” for male or lowercase “w” for female; any other value will not be recognized. Height and weight need to be passed in metric units, which means centimeters for the height and kilograms for the weight. In case you have inches or lbs, you need to convert the data before passing it to the widget.

13) userBraCup / userBraBust / userBraSystem

In case the user is female, we also need to know her bra size. To prefill the bra dropdowns, you can use these parameters. They are optional as well; depending on the bra system it might not be necessary to prefill userBraBust, for example. The currently supported bra systems are “EU”, “UK”, “US”, “AU”, “NZ”, “BE”, “ES”, “FR”, “IT”, “CZ” and “BR” (which won’t need bra bust) and you should pass them along with any bra values, because the widget would otherwise try to automatically determine the right one and might pick one that does not allow the other bra values you sent.

Questions?

We're happy to help. Send your question to integration@fitanalytics.com.