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

200 This is the session id hash.

"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:

First method: Permalink

GET https://vfr-v3-production.sizebay.technology/plugin/my-product-id?sid=*&permalink=*

Headers 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

Query Parameters

Name	Type	Description
permalink*	string	Product permalink
sid*	string	User identification

Second Method: SKU

GET https://vfr-v3-production.sizebay.technology/plugin/feed-product-id?sid=*&tenant-id=*&product-id=*

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

Query Parameters

Name	Type	Description
product-id*	string	Product SKU. Read more about that in https://support.google.com/merchants/answer/6324405?sjid=11564425063522710898-SA
sid*	string	Sizebay Session ID
tenant-id*	string	Your store ID

Both can return three possible responses:

Product Exists (200) ✅

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

Product does NOT Exist (404) ❌

"Not product found for *product-id* "

Server Error (500) ❌

This usually happens when the data provided is using an invalid format. It can either return an empty response, a BFF response (e.g: "500 for URL https://catalogue.sizeb[...]"), or, in corner cases, a `NullPointerException`.

In any of those cases, make sure to contact our support team to assist on whatever is necessary.

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 SizeCharts button
200 with "accessory": true"	Show only the SizeChart button

4. Opening the VFR & SizeChart

To display the SizeCharts or the Virtual Fitting Room is necessary to assemble the URL with the following information:

VFR or Sizechart experience

<iframe src="https://vfr-v3-production.sizebay.technology/V4/?mode=*&id=*&sid=*&tenantId=*&watchOpeningEvents=true&lang=*" />

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.

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)
sizesInStock	string	Product sizes in stock (available) ex: "S","M","L","XL"
countryValue	string	Country running plugin (ex: BR, US, MX, DE)

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

200 Recommendation found

{
  "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 [e-mail] for more info or assistance about it.

Controlling the buttons CTA triggers

If you're developing your own buttons for the CTA and is looking to find a way to properly control the VFR triggers, you can use our helper methods within window.SizebayParams

In the code sample below, you'll be able to understand how each declaration can be done.

/* If you're coming from an API integration perspective,
 * feel free to declare this variable on the method that suits you best.
*/
const productId = window.SizebayParams.id; 

function yourVfrCtaButton() {
    window.SizebayParams.openVFR(productId) // Opens the VFR for that Product ID
}

function yourChartCtaButton() {
    window.SizebayParams.openChart(productId) // Opens the Size Chart for that Product ID
}