1.1 Fit Finder Widget

The Fit Finder integration produces two scripts:

  • The pdp.js script, which will be added to (all) Product Details Pages (PDP). This script serves to: install the Fit Finder button, through which the user can open the Fit Finder size advisor, on the PDP. collect and send all the necessary data from the shop to the Fit Finder database to provide a recommendation.

  • The orderconfirmation.js script, which will be added to the checkout/ Order Confirmation Page (OCP). This script serves at the end of the user journey to: Connect items with a size recommendation and the purchased item help improve fit prediction models and the size recommendation engine Collect purchase data for Fit Insights reports

Neither of the scripts collects or stores any personal identifiable information on a user.

1.2 Integration Data Objects

Fit Finder relies on various elements of a shop’s website, which means the integration can be impacted by any changes made to these dependencies. Changes to a shop’s infrastructure or design can be expected over time but might cause Fit Finder to no longer load correctly.

Therefore Fit Finder integrations are built in a way to prevent these outages, resulting from changes to the dependency elements. Best practice to ensure a stable integration, we recommend to work with data objects on the PDP (Product Detail Page) and OCP (Order Confirmation Page). Fit Analytics will prepare these objects and they will contain only the necessary information Fit Finder requires. The shop’s technical resources will be responsible for implementing these objects to the PDP and OCP.

The Fit Finder data objects* will ensure a robust integration. Fit Analytics provides custom data objects for all new integrations.

  • It’s important to note that the pdp data object should always update with the correct values/data whenever a color or a product changes on the pdp.
  • The objects should be placed directly on the page and not via tag manager (e.g. Google Tag Manager), since the properties, e.g. color change or navigating to another PDP should update the object.

Product Detail Page (PDP) Object

fitAnalyticsData = {
    shopLanguage: "xx", // ISO 639-1, e.g. 'en'
    shopCountry: "XX", // ISO 3166-1, e.g. 'GB'
    mainImageLink: "xxxxx", // URL to thumbnail to be displayed within the widget
    userId: "xxxxx", // user ID (if logged), not email
    currentItemSubgroupId: "xxxx", // current color-level ID
    allItemSubgroupIds: ["xxx", "xxx", "xxx", "etc."], // all color-level IDs on the page
    shopSessionId: "xxxx", // shop session id: a first-party client generated session ID (can be a cookie) [we use it to track the purchase & keep our data persistent] session ID (can be a cookie)
    // [we use it to track the purchase & keep our data persistent]
    experimentFunnel: "xxxx", // in case of external A/B test
    sizes: [
        { value: "42", isAvailable: true },
        { value: "44", isAvailable: false },
        { value: "46", isAvailable: false },
    // helper functions or paths to functions (relative to window) to
    // select DOM elements or execute operations.
    operations: {
         @returns the HTML element of the add-to-cart button
        getAddToCartBtn: function () {},
         @returns the HTML element of the size chart button
        getSizeChartLink: function () {},
         This function should add the given size to cart for the given product id
         @param {string} productId
         @param {string} size
        addToCart: function (productId, size) {},
         Select the given size for the given product id
         @param {string} productId
         @param {string} size
        selectSize: function (productId, size) {},
         @returns {string} the currently selected size
        getCurrentSize: function () {},
         This is required for implementing the Multiple-Sizes-Alert (MSA) feature
         @returns {Promise|Object|Array} all current cart items
        getCartItems: function () {},
        // ...

Order Confirmation Page (OCP) Object

fitAnalyticsData = {
  orderId: "xxxxxx",
  shopLanguage: "xx", // ISO 639-1, e.g. 'en'
  shopCountry: "XX", // ISO 3166-1, e.g. 'GB'
  currency: "XXX", // ISO 4217, e.g. 'EUR'
  userId: "xxxx", // user ID (if logged), not email (MUST have same value as from the PDP for the same user)
  shopSessionId: "xxxx", // shop session id: a first-party client generated session ID (can be a cookie) [MUST have same value as from the PDP for the same session]
  products: [
      // purchased product nr 1
      size: "xx",
      itemId: "xxxxxxxxx", // size-level ID
      itemSubgroupId: "xxxxxxx", // color-level ID
      price: "XX", // per item
      quantity: "x", // number of purchased items
      gtin: "xxxxxxxxxxxxx", // EAN/GTIN/UTIN
      // purchased product nr 2
      size: "xx",
      itemId: "xxxxxxxxx",
      itemSubgroupId: "xxxxxxx",
      price: "XX",
      quantity: "x",
      gtin: "xxxxxxxxxxxxx",
    //... the same per each purchased product

Objects Elements Details

Element Description
currentItemSubGroupId The current item sub group ID identifies the article, on a color level basis, and tells Fit Finder for which garment it should load the fit prediction. It is the most important parameter, upon which all others depend. That serial describes each color variant within a single product style of a garment. (we can mention that our widget was built in a way that it needs and relies on a color-level-id)
mainThumbnail For the main thumbnail an absolute URL to a product image thumbnail needs to be provided. Thumbnail image dimensions should be at least 300 x 300 pixels for optimal appearance.
sizes Is an array of objects, which refer to the available sizes on the PDP. Each size object should have two properties: the size value and the value of the availability. The sizes should be passed in the identical format as seen on PDP and feed. Sending a different size code or format can not be used.
shopCountry & shopLanguage The combination of shop country and language is referred to as locale. The language parameter, allows the Fit Finder button and the widget content to initialize in that shop language. If not stated otherwise, the fallback language is English. The shop country also indicates, whether that locale includes Fit Finder support or not.
userID Is a unique ID (hashed) for logged in users and doesn’t depend on the session. It should be consistent and has the same value as on the OCP. It should be null/empty in case of guest users.
shopsessionID** Shop session ID is a term used internally by Fit Analytics but in essence describes the shop session (cookie). It is used to track the hosting shop’s session and the user’s journey between PDP and OCP

Shop Session ID

Due to updated security policies on iOS devices, it is often not possible for Fit Finder scripts to interact with 3rd party cookies, such as connect.sid. This is a growing issue, as our data shows that more users are viewing Fit Finder on iOS devices. Lack of session ID’s lead to issues tracking the user journey between PDP and OCP.

A solution for this problem is to retrieve a first party (generated shop side) session ID. In the integration object, it’s called shop session ID. The primary location for such an ID is a first party cookie, native to the shop’s site, though any identifier may be used as long as it adheres to these criteria:

  • It should be unique per visitor and preserved between visits from the same browser for the duration of their session.
  • Its value must stay the same when the visitor logs in or out.
  • It needs to be accessible on both PDP and OCP and it must have the same value for a single visitor on both pages
  • It should be safe from misuse in case. For example it shouldn't be possible to impersonate and/or personally identify the visitor in any way with just this identifier.
  • It could be theoretically derived from the shop's internal session ID, however then it should be definitely protected (e.g. hashed with a secure hash function like SHA256), to prevent abuse as described.
  • It must be readable by JavaScript. This means cookies with the httpOnly flag are not suited for this purpose.

You can check this PDF doc for more information concerning Data objects.

1.3 Object Operations

The Fit Finder data object includes helper functions to help execute the add to cart function.

Add To Cart Function

Fit Finder allows users to add the recommended size (primary recommendation or secondary recommendation) to the shopping basket directly from within Fit Finder. Adding the Add-to-cart feature to Fit Finder is done by inserting the cart callback parameter into the integration code. The helper function (addToCart) allows adding a specific size to the basket, which ‘mimics’ the shop’s process of adding a size to the cart.

addToCart: function (size, productId?, quantity=1) {}

Add To Cart Fallback

If the Add-to-Cart function can’t be provided, the fallback option would be to work with a combination of helper functions:

selectSize: this function selects the correspondent size DOM element of a given size (it takes a size value as parameter)

getAddToCartBtn: this function returns the DOM element of the add to cart/basket button element

Once the user gets a recommended available size, the widget will trigger the selectSize function to select that size. Then the getAddToCartBtn function will be triggered to click on the add to cart/basket button, and as a result the size will be added to cart/basket.

Get Size Chart Function

For analysis purposes we track clicks on the size-chart element. For this data to be collected, the shop needs to provide a way to get the DOM element of the size chart.

1.3.1 Data Object Validator

The Fit Finder data object validator is a way to test and validate that the data objects, being implemented by the shop’s technical resources, is as expected, all mandatory properties are there, property values are in the correct type and format, and operations are working properly.

The solution we have now is a simple js script that when run on a PDP with data object, it reads the object, validates the data and logs the validation results on the browser’s console.

How to use the script:

  • Calling the links:

The script can be called externally on a PDP / OCP with the data object provided. https://osiris.fitanalytics.com/pdp-checker.osiris.js

  • Using a JS injector:

A simple JS injector can be used to inject the script into the PDP / OCP with the data object provided.

The data object validation results can then be seen by opening the devTools' console tab.

1.4 Immediate Recommendation

Once a user has completed the recommendation flow and received a size recommendation, Fit Finder delivers size recommendations on the following Product Detail Pages (PDPs). This feature allows Fit Finder users to obtain recommendations immediately during the shopping journey or upon a user’s return to any supported PDP on the shop. The Fit Finder call to action (CTA) button will change to the immediate recommendation text for returning users and they will not have to go through the flow again.

Fit Finder Click To Action Text

Fit Finder Immediate Recommendation Text

1.5 Order Confirmation Page

Fit Finder integration produces two scripts, one script that runs on the product detail page and enables the visual front end functionality of Fit Finder and one script that runs on the checkout/order confirmation page. The orderconfirmation.js script, serves at the end of the user journey to connect purchases, track the user journey from size recommendation to purchase and helps improve fit prediction models.

1.6 Customization

Parts of the Fit Finder experience can be customized to support a shop’s visual brand guidelines. Within Fit Finder standard integration these following elements are customizable:

Shop Logo:

dimensions of the logo placeholder are W: 200 px and H: 60px max or higher resolution.limit: Logo should not be bigger than 10 MB.Format: The best option is SVG, however we can also work with JPG and PNG. If a shop can’t provide one of the latter formats, the resolution of the image should be at least 300ppi.

Button Color:

(CTA) button, Immediate recommendation (IR) button, Add-to-Cart (A2C) button and feature tool tips, can be customized in a brand color.brand colors must be specified as a six-digit hexadecimal valueCTA button and tool tips, different brand color can be used, a primary HEX and secondary HEXmost cases the Primary HEX should be dark enough for the text upon it to be white as it is here:

Classic Fit Finder Designs:

Custom Color Design:

Customizable Tool Tips:

1.7 How does widget.js work

To interact with Fit Finder, the widget needs to collect certain information, such as the shop country, the language, the color-id of the selected product. The Fit Finder script fetches this information on the shop and will also install the button. The widget’s size is written in native coffeescript without relying on frameworks for various reasons:

  • the widget’s size is minimal
  • the widget is cross platform and works with different client shops
  • we have full control over widget functionalities

After collecting the necessary data and interacting with a user, Fit Finder recommends a size to the user, and user feed data is stored in the widget. In this process no personal identifiable data of any user is used or stored.

1.8 Compatibility

Fit Finder’s current code base offers support for a wide range of legacy browsers and devices. It can operate without jQuery or alternatively, load 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 Fit Finder widget code.


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