Implementation (via API)

Guidelines for the implementation of Sizebay's VFR and SizeCharts via API

Flowchart

To display the buttons and access the VFR experience from a product page, it is necessary to first identify the user and get the product information:

Starter Guide

ATTENTION: The asterisk (*) symbol, when placed next to a field or item in forms or documentation, typically denotes that the information is mandatory or required.

ATTENTION: Sending the country value is only mandatory if you want to segregate the data by country. If there is no need to segregate by country, you can proceed without providing this information.

We have created a Demo Application that you can use as a start guide. You can find this on our Github account. -> https://github.com/sizebay/vfr-implantation-demo/

1. Identifying the Sizebay User (Sizebay Session ID)

The Sizebay Session ID (SID) is used by our services to identify a user. This ID must be stored in the cookies to be consulted in the application. The first step to start the service is to check if a cookie called SIZEBAY_SESSION_ID_V4 key exists.

  • If it exists, simply use the hash returned for consultation while using the application.

  • If not, get a SID using the route bellow and save this hash in your browser's cookies with the SIZEBAY_SESSION_ID_V4 key.

Session-id

GET https://vfr-v3-production.sizebay.technology/api/me/session-id

Creates a new user or returns the existing one

"16006C10A517168a7bc37538415fa3b49b80f4573be8"

If the hash already exists in cookies, it is not necessary to request a new one. This route should only be used for creation.

2. Getting the product's information

Before displaying the buttons it is necessary to check if the product exists in our database using one of the routes below.

ATTENTION: Make sure to only use ONE of the methods described below, since they differ in context.

ATTENTION: Sending the country value is only mandatory if you want to segregate the data by country. If there is no need to segregate by country, you can proceed without providing this information.

In order to do that, there are two possible methods:

Both can return three possible responses:

{
  "id": "5286077", // product id
  "accessory": false, // if the product is an accessory
  "shoe": false // if the product is a shoe
}

Notice that every and each call to the above GET method for the product's information API is contabilized for statistical and billing purposes, and counts as one hit per success status response - 200 OK

3. Showing the Sizebay buttons

The Sizebay buttons (Virtual Fitting Room and SizeCharts) must be executed or not considering the product information, as shown below:

Message

Action

404 with "Not product found for [....]"

Don't show any button

200 with "accessory": false"

Show the VFR and SizeChart buttons

200 with "accessory": true"

Show only the SizeChart button

4. Opening the Virtual Fitting Room (VFR) and Size Chart via iFrame

To embed the Virtual Fitting Room (VFR) or the Size Chart into your product pages, use the appropriate iFrame URL based on the type of product (shoes or non-shoes).

iFrame URLs by Use Cases

Use Case

iFrame URL

VFR – Non-shoe products

https://vfr-v3-production.sizebay.technology/V4/?mode=vfr&id=*&sid=*&tenantId=*&watchOpeningEvents=true&lang=*&isMeasurementsTableEnabled=true

VFR – Shoe products

https://new-shoe-experience.sizebay.technology/?mode=vfr&id=*&sid=*&tenantId=*&watchOpeningEvents=true&lang=*&isMeasurementsTableEnabled=true&brandsComparison=*

Size Chart

https://measurements-table.sizebay.technology/?id=*&sid=*&tenantId=*&watchOpeningEvents=true&lang=*&isMeasurementsTableEnabled=true

Query Parameters

Name

Type

Description

mode*

string

Defines whether the measurement chart ("chart") or the virtual fitting room ("vfr") will be displayed

id*

string

Sizebay's Product ID

sid*

string

Sizebay Session ID

tenantId*

string

Store ID

lang*

string

Main language of the service (ex: br, en, es, de)

watchOpeningEvents*

boolean

Parameter that enable the events for plugin-opened and table-opened (should be true)

isMeasurementsTableEnabled*

boolean

Must be set to true to display the most up-to-date layout

brandsComparison*

boolean

For shoes: enables recommendation based on brand comparisons

sizesInStock

string

Product sizes in stock (available) ex: "S","M","L","XL"

countryValue

string

Country running plugin (ex: BR, US, MX, DE)

ATTENTION: Sending the country value is only mandatory if you want to segregate the data by country. If there is no need to segregate by country, you can proceed without providing this information.

The parameter watchOpeningEvents is mandatory for API implantations. Without, we won't be collecting all the events available.

Check more custom param's on 7. Utilities and Tweaks

5. Recommendation on the PDP

The recommendation on the page uses the recommendedSize and profileName property to display the recommended size for the active profile. If there is no recommendation, the recommended size will be null. In the web version, we generate an element that is built around these two values.

Recommendation on page

ATTENTION: Sending the country value is only mandatory if you want to segregate the data by country. If there is no need to segregate by country, you can proceed without providing this information.

GET https://vfr-v3-production.sizebay.technology/api/me/analysis/5286077?sid=*&tenant=*

Header Parameters

Name
Description

x-szb-country

Country running plugin (ex: BR, US, MX, DE)

x-szb-device*

User device

Possible values: DESKTOP, MOBILE, TABLET, APP

x-szb-tenant-id*

Store ID

Path Parameters

Name
Type
Description

*

integer

Product Identification (Sizebay's Product ID)

Query Parameters

Name
Type
Description

sid*

string

User identification

tenant*

string

Store ID

{
  "analysisResponse": null, // analysis information
  "productInfo": null, // product information
  "recommendedSize": "M", // recommended size
  "productGender": "F", // profile gender
  "profileName": "Você" // profile name
}

5.1 Adding the device through the recommendation event

In order for Sizebay to understand where the recommendation event is coming from, it's important to have the property `device` passed through the request headers. This also helps consistency on the user flow, where we'll be able to identify the user through its device. Passing the device on your request is very straightforward.

Add `x-szb-device` within the request headers (with logic included!)

function isMobile() {
  const toMatch = [/Android/i, /webOS/i, /iPhone/i, /iPad/i, /iPod/i, /BlackBerry/i, /Windows Phone/i]

  return toMatch.some((toMatchItem) => navigator.userAgent.match(toMatchItem))
}

function isTablet() {
  const toMatch = [/iPad/i, /Tablet/i]

  return toMatch.some((toMatchItem) => navigator.userAgent.match(toMatchItem))
}

function isWebView() {
  return window.navigator.standalone === true
}

/** This function returns the current device from the Window object. **/
function getCurrentDevice() {
  if (isMobile() && !isWebView()) return 'mobile'
  if (isWebView()) return 'app'
  if (isTablet()) return 'tablet'

  return 'desktop'
}

const request = await fetch(SIZEBAY_RECOMMENDATION_URL, {
  headers: {
    // rest of your headers
    'x-szb-device': getCurrentDevice(),
  }
})

6. Initializing the VFR (via WebView)

The integration process is very similar to the iframe, seen previously. WebView should load the URLs seen in "Opening the VFR & SizeChart" and "SizeCharts" respectively. The process for instantiating a WebView in your application is quite simple.

Declare a Tag WebView

<WebView
    android:id="@+id/webview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
/>

Pass the URL for loading the content

WebView virtualFittingView = (WebView) findViewById(R.id.webview);
virtualFittingView.loadUrl(URL_VFR_permalink);

Replace the URL_VFR_permalink for the appropriate permalink.

7. Utilities and Tweaks

Custom product image

If you wish to explicitly define which product image to be rendered by the VFR, you can pass to our URL the query param pageProductImg=www.your-store.com/product-image-url.png.

Custom product sizes

If you wish to explicitly define which sizes are available to be rendered by the VFR, add to our iFrame/WebView URL the query param sizes=YOUR,SIZE,LIST,HERE. Where each item represents a size, separated by a comma.

Sizes in Stock

This parameter monitor stock shortage and are used in analytics and reports. Add to our iFrame/WebView URL the query param sizesInStock=YOUR,SIZE,LIST,HERE . Where each item represents a size, separated by a comma. Sizes that are out of stock must not be added.

Country

This parameter informs which country the plugin is being used in. With this information we are able to create more complete reports. To find out which values ​​are accepted, click here.

DIY Close Modal

If you're looking to have more control over the closing modal element and its triggers, you can pass to our URL the query param disableCloseApp=true

By disabling the close app triggers, you'll have to control the modal closing event by yourself, whilst also providing its proper stylings and layout. You can always talk to us at [email protected] for more info or assistance about it.

Last updated

Was this helpful?