# Service Implementation (API)

![Flowchart](/files/wAw3X1WDqZrEqRtxr9c8)

To display the buttons and access the VFR experience from a product page, it is necessary to first [identify the user](/size-and-fit-implementation/service-implementation-api.md#1-identifying-the-sizebay-user-sizebay-session-id) and [get the product information](/size-and-fit-implementation/service-implementation-api.md#2-getting-the-products-information):

### Starter Guide

{% hint style="danger" %}
Sizebay strongly recommends integrating the Virtual Fitting Room asynchronously, using non-blocking loading.<br>

Blocking implementations may impact performance metrics, delay PDP rendering, and cause page freezes under latency conditions.\
\
The asynchronous approach ensures the page remains functional even during temporary service unavailability and aligns with best practices for third-party integrations.
{% endhint %}

{% hint style="warning" %}
**ATTENTION:** The asterisk (<mark style="color:red;">`*`</mark>) symbol, when placed next to a field or item in forms or documentation, typically denotes that the information is mandatory or required.&#x20;
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

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.<br>
* **If not**, [get a SID](/size-and-fit-implementation/service-implementation-api.md#session-id) using the route bellow and save this hash in your browser's cookies with the **SIZEBAY\_SESSION\_ID\_V4 key**.

## Session-id

<mark style="color:blue;">`GET`</mark> `https://vfr-v3-production.sizebay.technology/api/me/session-id`

Creates a new user or returns the existing one

{% tabs %}
{% tab title="200 This is the session id hash." %}

```
"16006C10A517168a7bc37538415fa3b49b80f4573be8"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If the hash already exists in cookies, it is not necessary to request a new one. This route should only be used for creation.&#x20;
{% endhint %}

### **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.

{% hint style="warning" %}
**ATTENTION:** Make sure to only use **ONE** of the methods described below, since they differ in context.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

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

{% tabs %}
{% tab title="First method: Permalink" %} <mark style="color:blue;">`GET`</mark> `https://vfr-v3-production.sizebay.technology/plugin/my-product-id?sid=*&permalink=*`

#### Headers Parameters

<table><thead><tr><th width="342">Name</th><th>Description</th></tr></thead><tbody><tr><td><a href="#country">x-szb-country</a></td><td>Country running plugin (ex: BR, US, MX, DE)</td></tr><tr><td><a href="#id-5.1-adding-the-device-through-the-recommendation-event">x-szb-device</a><mark style="color:red;">*</mark></td><td><p>User device</p><p>Possible values: <em>DESKTOP</em>, <em>MOBILE</em>, <em>TABLET</em>, <em>APP</em></p></td></tr><tr><td>x-szb-tenant-id<mark style="color:red;">*</mark></td><td>Store ID</td></tr></tbody></table>

#### Query Parameters

| Name                                        | Type   | Description         |
| ------------------------------------------- | ------ | ------------------- |
| permalink<mark style="color:red;">\*</mark> | string | Product permalink   |
| sid<mark style="color:red;">\*</mark>       | string | User identification |
| {% endtab %}                                |        |                     |

{% tab title="Second Method: SKU" %} <mark style="color:blue;">`GET`</mark> `https://vfr-v3-production.sizebay.technology/plugin/feed-product-id?sid=*&tenant-id=*&product-id=*`

#### Header Parameters

<table><thead><tr><th width="342">Name</th><th>Description</th></tr></thead><tbody><tr><td><a href="#country">x-szb-country</a></td><td>Country running plugin (ex: BR, US, MX, DE)</td></tr><tr><td><a href="#id-5.1-adding-the-device-through-the-recommendation-event">x-szb-device</a><mark style="color:red;">*</mark></td><td><p>User device</p><p>Possible values: <em>DESKTOP</em>, <em>MOBILE</em>, <em>TABLET</em>, <em>APP</em></p></td></tr><tr><td>x-szb-tenant-id<mark style="color:red;">*</mark></td><td>Store ID</td></tr></tbody></table>

#### Query Parameters

| Name                                         | Type   | Description                                                                                                             |
| -------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| product-id<mark style="color:red;">\*</mark> | string | Product SKU. Read more about that in <https://support.google.com/merchants/answer/6324405?sjid=11564425063522710898-SA> |
| sid<mark style="color:red;">\*</mark>        | string | Sizebay Session ID                                                                                                      |
| tenant-id<mark style="color:red;">\*</mark>  | string | Your store ID                                                                                                           |
| {% endtab %}                                 |        |                                                                                                                         |
| {% endtabs %}                                |        |                                                                                                                         |

#### Both can return three possible responses:

{% tabs %}
{% tab title="Product Exists (200) ✅" %}

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

{% endtab %}

{% tab title="Product does NOT Exist (404) ❌" %}

```
"Not product found for *product-id* "
```

{% endtab %}

{% tab title="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.
{% endtab %}
{% endtabs %}

{% hint style="danger" %}
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
{% endhint %}

### 3. Showing the Sizebay buttons&#x20;

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

<table data-header-hidden><thead><tr><th width="235.5625"></th><th></th></tr></thead><tbody><tr><td>Use Case</td><td>iFrame URL</td></tr><tr><td>VFR – Non-shoe products</td><td><code>https://vfr-v3-production.sizebay.technology/V4/?mode=vfr&#x26;id=*&#x26;sid=*&#x26;tenantId=*&#x26;watchOpeningEvents=true&#x26;lang=*&#x26;device=*</code></td></tr><tr><td>VFR – Shoe products</td><td><code>https://new-shoe-experience.sizebay.technology/?mode=vfr&#x26;id=*&#x26;sid=*&#x26;tenantId=*&#x26;watchOpeningEvents=true&#x26;lang=*&#x26;brandsComparison=*&#x26;device=*</code></td></tr><tr><td>Size Chart</td><td><code>https://measurements-table.sizebay.technology/?id=*&#x26;sid=*&#x26;tenantId=*&#x26;watchOpeningEvents=true&#x26;lang=*&#x26;device=*</code></td></tr></tbody></table>

#### Query Parameters

|                                                      |         |                                                                                                            |
| ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| Name                                                 | Type    | Description                                                                                                |
| mode<mark style="color:red;">\*</mark>               | string  | Defines whether the measurement chart ("`chart`") or the virtual fitting room ("`vfr`") will be displayed  |
| id<mark style="color:red;">\*</mark>                 | string  | Sizebay's Product ID                                                                                       |
| sid<mark style="color:red;">\*</mark>                | string  | Sizebay Session  ID                                                                                        |
| tenantId<mark style="color:red;">\*</mark>           | string  | Store ID                                                                                                   |
| lang<mark style="color:red;">\*</mark>               | string  | Main language of the service (ex: `br`, `en`, `es`, `de`)                                                  |
| watchOpeningEvents<mark style="color:red;">\*</mark> | boolean | Parameter that enable the events for plugin-opened and table-opened (should be `true`)                     |
| brandsComparison<mark style="color:red;">\*</mark>   | boolean | For shoes: enables recommendation based on brand comparisons                                               |
| [sizesInStock](#sizes-in-stock)                      | string  | Product sizes in stock (available) ex:   `"S","M","L","XL"`                                                |
| [countryValue](#country)                             | string  | Country running plugin (ex: BR, US, MX, DE)                                                                |
| device<mark style="color:red;">\*</mark>             | string  | <p>User device</p><p>Possible values: <em>DESKTOP</em>, <em>MOBILE</em>, <em>TABLET</em>, <em>APP</em></p> |

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="warning" %}
The parameter **`watchOpeningEvents`** is **mandatory** for API implantations. Without, we won't be collecting all the events available.
{% endhint %}

{% hint style="info" %}
Check more custom param's on [#id-7.-utilities-and-tweaks](#id-7.-utilities-and-tweaks "mention")
{% endhint %}

### **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

{% hint style="warning" %}
**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.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://vfr-v3-production.sizebay.technology/api/me/analysis/5286077?sid=*&tenant=*`

#### Header Parameters

| Name                                                                                                         | Description                                                                                                |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| [x-szb-country](#country)                                                                                    | Country running plugin (ex: BR, US, MX, DE)                                                                |
| [x-szb-device](#id-5.1-adding-the-device-through-the-recommendation-event)<mark style="color:red;">\*</mark> | <p>User device</p><p>Possible values: <em>DESKTOP</em>, <em>MOBILE</em>, <em>TABLET</em>, <em>APP</em></p> |
| x-szb-tenant-id<mark style="color:red;">\*</mark>                                                            | Store ID                                                                                                   |

#### Path Parameters

| Name                               | Type    | Description                                   |
| ---------------------------------- | ------- | --------------------------------------------- |
| <mark style="color:red;">\*</mark> | integer | Product Identification (Sizebay's Product ID) |

#### Query Parameters

| Name                                     | Type   | Description         |
| ---------------------------------------- | ------ | ------------------- |
| sid<mark style="color:red;">\*</mark>    | string | User identification |
| tenant<mark style="color:red;">\*</mark> | string | Store ID            |

{% tabs %}
{% tab title="200 Recommendation found" %}

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

{% endtab %}
{% endtabs %}

### **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!)

```javascript
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](/size-and-fit-implementation/service-implementation-api.md#vfr-or-sizechat-experience)" and "SizeCharts" respectively. **The process for instantiating a WebView in your application is quite simple.**

#### Declare a Tag WebView

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

#### Pass the URL for loading the content

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

{% hint style="info" %}
Replace the URL\_VFR\_permalink for the appropriate permalink.
{% endhint %}

### **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, you must add to our iFrame/WebView URL the query param:

```
sizes=BASE64_ENCODED_LIST
```

Where `BASE64_ENCODED_LIST` is a Base64-encoded string of your size list, separated by commas.\
For example, if your sizes are:&#x20;

```
36,38,40,42
```

You must first encode them in Base64, resulting in:

```
WyIzNiIsIjM4IiwiNDAiLCI0MiJd
```

And then pass it as:

```
...&sizes=WyIzNiIsIjM4IiwiNDAiLCI0MiJd
```

#### 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](/size-and-fit-order-tracking/supported-countries-and-currencies.md).

#### 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`

{% hint style="info" %}
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 **<support@sizebay.com>** for more info or assistance about it.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sizebay.com/size-and-fit-implementation/service-implementation-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.