Native Apps Integration

Supported SDKs

iOS - https://github.com/UPcload/FitAnalytics-WebWidget-iOS
Android - https://github.com/UPcload/FitAnalytics-WebWidget-Android
React Native - https://github.com/UPcload/FitAnalytics-WebView-ReactNative

1. Common Widget Interface

There are several native app Fit Finder SDKs, however the concept and the mode of integration is similar between them. Each SDK exposes an imperative object-oriented interface - the FitFinderWidget class, where almost all parameters are same or very similar regardless of language used and the same applies to exposed methods and callbacks. It requires an instance of WebView in which the main widget code runs and which is also used for displaying the UI for entering the customer's measurements or preferences.

The general mode of interface is asynchronous and event-driven. Each method call initiates a message passed to the embedded webpage where the actual widget is running and any reaction to the call arrives in the form of event callback. For example calling the getRecommendation() method will eventually result in native app's provided onRecommendation function being called back with the result of the recommendation passed as an argument.

Exact names of parameters and especially provided callbacks and methods may differ between platform implementations. The naming tries to follow platform's usual practices, e.g. onOpen callback in React Native SDK has an equivalent called webWidgetDidOpen in iOS SDK.

The widget inside the embedded page is stateful, ie. it keeps information about the corrent context (country, language, etc) and the current product (category, gender etc). It can be reconfigured by calling the reconfigure method.

2. Integration Basics

The usual integration has a following structure:

The native app code creates an instance of FitAnalyticsWidget in its respective language with configuration parameters. Several parameters are callbacks (or equivalents), which are necessary for getting results back from the widget.
At that point that the embedded widget will begin loading into the WebView instance and once the loading has finished, the SDK will call the onInit callback.
Depending on user's action the app will call a widget methods like open, getRecommendation or reconfigure and SDK will in turn call registered corresponding callbacks, when it has received a result of the operation.

Here's an example in Javascript pseudocode, which contains usual parameters and callbacks:

let widget = new FitAnalyticsWidget({
  shopPrefix: "yourshopname",
  productSerial: "yourshopname-abcd123456",
  shopLanguage: "en", // ISO 639-1, e.g. ‘es’, 'pt', 'de'
  shopCountry: "US", // ISO 3166-1, e.g. ‘GB’, 'ES', 'DE'
  thumb: "http://yourshopname.com/images/garment.jpg",
  userId: "Cz5b1-X2312",
  shopSessionId: "023e23-fa3334d923-344d8a783",
  manufacturedSizes: {
    "S": true,  // in stock
    "M": false, // out of stock
    "L": true   // in stock
  },
  onInit: () {
    // the widget is loaded and ready
    widget.load()
  },
  onProductLoad: () {
    // show the button and/or call getRecommendation
  },
  onProductError: (productSerial) {
    // the product is unsupported, hide/unload the button
  },
  onRecommend: (productSerial, size) {
    // present the recommended size to the customer
  },
  onOpen: (productSerial) {
    // show the widget UI inside the WebView to the customer
  },
})

// user clicks the Size Advisor button
widget.open("yourshopname-abcd123456")

// when the user navigates to another product
widget.reconfigure("yourshopname-def7890", {
  manufacturedSizes: {
    "36": true,
    "38": false,
    "40": false,
  }
})

shopPrefix - (required) given merchant identifier
productSerial - (required) product ID for Fit Analytics, usually in the form of <shopPrefix>-<productId>

The productSerial tells Fit Finder for which garment it should load the information. 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 - (required) a dictionary that list all in-stock and out-of-stock sizes of the specified product.

The manufacturedSizes parameter allows you to pass a list of sizes for that specific garment to Fit Finder. 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.

onProductLoad - a callback that is executed once Fit Finder loads the product information

The onProductLoad function is called when Fit Finder has successfully loaded the product data associated with the productSerial — in other words, when Fit Finder has the relevant data and is ready to be opened by the user.

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

The callback function receives the productSerial as its only parameter.

onProductError - a callback that is executed once Fit Finder determined that the product is unsupported
onRecommend - a callback executed when the size recommendation has been made
widget.open() - will cause the widget to display the UI inside the Web
widget.reconfigure() - will pass new configuration options to the widget and possibly cause it to load a new product

Localization

There are several important localization parameters that not only determine language of interface, but other aspects of the Fit Finder.

shopCountry: (required) the country of the store, which can determine the support status, the sizing system and few other aspects of the product
shopLanguage: (required) sets the language of the Fit Finder interface; can also play role in sizing system
metric: for choosing between imperial or metric system of the interface

For more details see the Parameter Reference section.

Immediate Recommendation

When 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 them to receive a size recommendation for additional products without opening the widget. This feature allows the user to see their recommended size directly on the product page, without requiring them to re-open the Fit Finder.

To enable this behavior, the integration code must include:

a call to getRecommendation(...), which uses their previously-entered data to retrieve an immediate size recommendation,
the onRecommend callback, which may receive three possible values:
- "new user" - the user’s measurements data are not complete, and therefore Fit Finder 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

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 Fit Finder. Adding the Add-to-cart feature to Fit Finder can be done by inserting the cart callback parameter into the integration code.

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

The callback function is called when the user clicks on the “Add size X to cart” button in Fit Finder. The button is only visible when the cart option is enabled (or if the onCart callback function is defined in React Native), otherwise it is replaced with a “Return to store” button. The size parameter will always contain the currently selected size from the Fit Finder widget as a string. For example, if the user selects size “M” in Fit Finder and then clicks the “Add to cart” button, Fit Finder 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.

The reconfigure(productSerial, options) method allows the integration code to change the configuration of the Fit Finder widget after the initialization.

productSerial .. (string) new product identifier, when the product has changed, can be null; when set, the new product information will be loaded into the embedded widget

options .. (object) an object with new Fit Finder widget configuration options, see below a list of possible parameters that can be configured through the options object.

Additional options that may be changed after Fit Finder initialization and specified as a part of the options argument are:

manufacturedSizes
sizeRegion
thumb
metric
shopCountry
language
userId

The reconfigure method is useful when new products are dynamically loaded on the PDP. The integration code can use it to adjust the internal Fit Finder state immediatelly after a new product has been selected by the user and ensure that the Fit Finder state is consistent with the currently visible page state (i.e. the current viewed product, available sizes, thumbnail, etc.).

The reconfigure method is an alternative to the open and getRecommendation methods as it allows the integration code to change the Fit Finder configuration, but the reconfigure method doesn't trigger any additional action (like opening the Fit Finder or requesting a recommendation), unlike those other methods.

When the productSerial is specified and is different from the previous one, a new product will be loaded and the SDK will call onLoad callback when finished or onError when the loading fails (ie. product is unsupported).

3. Parameter Reference

Shop & product parameters

shopPrefix - (required) given merchant identifier; required in general, but especially useful for error handling and reporting
productSerial: product ID for Fit Finder, usually in the form of <shopname>-<product_id>. The productSerial tells Fit Finder for which garment it should load the fit prediction. It is the most important parameter, upon which all others depend.
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.
manufacturedSizes: The manufacturedSizes parameter 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.
shopLanguage: en / de / fr / es / it / ru / nl / fi / tr / ro / pl / sv ...
This parameter manually forces Fit Finder 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, the SDK return with an error when loading the product.
metric: 0 / 1 / 2
Usually, we are able to determine whether imperial or metric system should be used in Fit Finder 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 Fit Finder to use the imperial system, but with stones instead of pounds as weight units.
cart: (boolean) Enable the add-to-cart integration; specifically, if this is enabled and the recommended size is available, the widget will display the Add-to-cart button on the results screen. When the user clicks the button, the SDK will call the provided onCart callback. This option is ignored on React Native platform.

Customer identifiers

There are several parameters for identifying the customer in general, the following ones are relevant for the native SDK:

userId: identifier of a registered and logged-in customer in merchant's system
shopSessionId: unique session ID of the customer, regardless of their logged-in status

For more detailed discussion of different identifiers, see: https://developers.fitanalytics.com/api#customer-ids-profiles

The embedded widget and the SDK handle the internal session ID transparently, so the native app doesn't need to deal with it.

Callbacks

onProductLoad: called once Fit Finder loads the product information. The onProductLoad function is called when Fit Finder has successfully loaded the product data associated with the productSerial — in other words, when Fit Finder has the relevant data and is ready to be opened by the user.
onProductError: called once Fit Finder fails to load the product information. This usually means that product is not supported by the Fit Finder, due unsupported category etc. It receives the productSerial as the first parameter.
onOpen: called when the Fit Finder widget displays its UI inside the WebView, after calling the widget.open method. This means that the WebView can be shown to the user and it should contain the UI, ie. it's not an empty page.
onClose: called when Fit Finder 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 Fit Finder through the “Add to cart” button and triggers the cart callback.
onCart: called when the user clicks on the “Add to cart” button in Fit Finder. 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 Fit Finder as a string. For example, if the user selects size “M” in Fit Finder and then clicks the “Add to cart” button, Fit Finder 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.
onRecommend: called when the size recommendation data is retrieved, after calling widget.getRecommendation() method (please see the Immediate Recommendation section above). 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 Fit Finder 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.

4. Sharing purchase data

It is crucial for your shop to share purchase data with Fit Analytics Innovation. There are two main reasons for this:

Business reporting becomes incomplete without purchase data from your mobile apps. Including purchases from all sources - websites as well as mobile apps - will enable powerful analytics on how the end users interact with your website and how Fit Finder contributes to reducing returns.
Our machine learning models use purchase and returns data for training so that Fit Finder can make accurate size recommendations. If purchase data from mobile apps is missing, this may have an adverse effect on size recommendation accuracy.

You can find the purchase interface for each SDK in the links below:

Required fields

Each purchase event should contain the following information.

order id: an id of the order.
user id: relevant if your shop uses an ID for users across multiple sessions; if visitors are not logged in, it should be null. Should be an alphanumeric value, not an incrementable integer.
shop session id: a unique session ID of the customer, regardless of their logged-in status. You can find the documentation on how to define this identifier here.
product serial: the same identifier that you sent to Fit Finder via the productSerial parameter. Should include your shop code.
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). This value should match the ID (or equivalent) in the returns feed and the ID (or equivalent) field in the product feed.
ean: a 13-digits universal barcode that identifies the product and size (EAN/GTIN in wikipedia). If your EAN is shorter than 13 characters, please add padding zeroes in the beginning to make the string 13 characters long.
purchased size: the purchased size, e.g. "M".
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)
quantity: number | string; The quantity that the user purchased of a specific product.
price: price of the purchased item (please note that we use ISO 4217 for specifying the currency), e. g. EUR