Smart Size Chart

A script to support e-commerce websites in providing garment size recommendations.

Quick Start Guide

For Shopify Users

To integrate the Smart Size Chart on your Shopify site, follow these quick steps:

Install a Private Shopify App for Bold Metrics Access For Garment Data Access
Add the Smart Size Chart Script To Your PDPs
Add the Bold Metrics div as well as the `window._boldmetrics` Object To Your PDPs
Integrate 'Add To Cart' Functionality To Maximize Conversion, either using the bmi_add_to_cart event or by using the bmi_selected_item event

For Non-Shopify Users

To integrate the Smart Size Chart on your site, follow these quick steps

Provide an initial set of garment data according to the instructions provided by your Bold Metrics representative.
Provide an initial product feed for review
Add the Smart Size Chart Script To Your PDPs
Add the Bold Metrics div as well as the `window_boldmetrics` object to your PDPs
Integrate 'Add To Cart' Functionality To Maximize Conversion, either using the bmi_add_to_cart event or by using the bmi_selected_item event

Required Product Data

Shopify Sites

Bold Metrics requires you to install a Private Shopify App, which grants Bold Metrics API access to your product data. We check your product catalog daily to check for product updates so your customers will get recommendations for the latest products.

Follow these steps to install a Private Shopify App:

From your Shopify admin, go to Apps in the left navigation bar.
Click App and sales channel settings in the command palette.
Click Develop apps.
Click Create an app.
Enter a name for your app that describes this application related to Bold Metrics.
Click Create app.
Click Admin API Configuration and select Edit.
In the search toolbar, search products, and select read_products.
In the search toolbar, now search orders, and select read_orders.
Click Save.
Select the API Credentials tab, and under Access tokens, click Install App (select Install if a popup is shown).
Select reveal token once, and copy the token. In the API key and secret key section, copy the API Key and API Secret key and send all three to Bold Metrics.

Non-Shopify Sites

Bold Metrics requires product data for products Bold Metrics will support. Depending on the product types and available data, your team may be asked to fill out a product template, provide a feed via FTP, or expose data in the browser.

Depending on the next steps, your account representative will communicate timeline and subsequent steps to complete onboarding.

    {
        tags: ['shirt'],
        description: 'Look great in our v-neck t shirt shirt!',
        id: '12345',
        type: 'Apparel & Accessories > Clothing > Shirts & Tops', 
        price: 49.99,
        sizechart: 'mens_tops',
        primaryDimension: 'ALPHA', 
        secondaryDimensions: [],
        title: 'Threadchoice V Neck T-Shirt',
        variants: [
            {
                id: 'SKU-12345-SMALL', 
                size: 'Small', 
                fit: 'Slim',
                sku: 'SKU-12345-999', 
                sizechart: 'mens_tops_slim', 
                available: true, 
                additionalMetadata: {} 
            },
            ...
        ] 
    }, ...
]

Integrating the Smart Size Chart

Adding Configuration and a Script Tag

Include this script tag in your Product Template (PDP) if you are a Shopify client, or in the <head> element of your PDP page if you are a non-Shopify client.

Do not add this to all pages, only the PDP. Please ensure that this script is only included once on your PDP.

<script async type="text/javascript" src="https://d2hicexbdkkc9q.cloudfront.net/ssc.production.js"></script>

Adding the boldmetrics div to your PDP

Add the following element at the location where you’d like to load the 'Find My Size' button. \

Non-Shopify Site Instructions

data-garment is the product ID for a given PDP. This product ID is expected to be found in your purchase and returns data.
data-measurement is a value identifying the size chart or category.

<div id="boldmetrics-ssc-default"
     data-garment="PRODUCT ID GOES HERE"
     data-measurement="SIZE CHART NAME GOES HERE">
</div>

Shopify Site Instructions

data-garment is the product title for a given PDP. This product title is expected to be found in your purchase and returns data.

<div id="boldmetrics-ssc-default"
     data-garment="{{ product.title }}">
</div>

After following the above instructions, a styled button will render by default:

Customizing Button Styles

Various aspects of the button's UI can be customized easily, by adding data attributes to the element.

The available customizations include:

data-button-mode = sets the button to either light purple or black. Should be set as “light” or “dark".
data-text-case = sets the text to either upper or title case. Should be set as “upper” or “title”.
data-background-color = sets background color (ex, '#4169E1')
data-border-radius = sets border radius in px (ex: '2px')
data-font-family = sets font family (ex: "cursive", "monospace", "Gill Sans Extrabold", "Helvetica")

For instance, if I wanted to turn on 'dark' mode, set the text case to 'upper', and the font-family to 'Helvetica', my boldmetrics div's code may look something like:

<div
    id="boldmetrics-ssc-default"
    data-button-mode="dark"
    data-text-case="upper"
    data-font-family="Helvetica"
    ...
/>

Resulting in a button that looks like:

Adding window._boldmetrics Object to your PDP

In order for Bold Metrics to capture all product information, please add the following JavaScript to your PDP. For Shopify users, this leverages liquid templates to pull product data in JSON format.

Non-Shopify Sites

Please see the various object definitions below to see all required parameters. Please note, all items marked 'Required' or 'Conditionally Required' are necessary for Bold Metrics' Smart Size Chart to function on a PDP.

<script>
    window._boldmetrics = {
        locale: 'en-US',
        product: {
            tags: ['button-down', 'shirt'],
            description: 'Look great in our button down shirt!',
            id: '12345',
            type: 'Apparel & Accessories > Clothing > Shirts & Tops', 
            price: 49.99,
            sizechart: 'mens_tops',
            primaryDimension: 'ALPHA', 
            secondaryDimensions: ['LENGTH:SLEEVE'],
            title: 'Threadchoice Button Down Shirt',
            variants: [
                {
                    id: 'SKU-12345-SMALL', 
                    description: 'Mens Shirt Small 32/33 - Slim Fit',
                    size: 'Small 32/33', 
                    fit: 'Slim',
                    sku: 'SKU-12345-999',
                    sizechart: 'mens_tops_slim', 
                    available: true, 
                    additionalMetadata: {}
                },
                ...
            ]
        }
    }
</script>

Object API Contract Definition

key

type

description

locale

String

Required. BCP 47 language + country code for PDP locale (en-US, en-GB, fr-FR, etc)

product

Object<Product>

Required. Top level object for product field, see object definition below

Product Object Contract Definition

Key

Type

Notes

id

String | Number

Required. Top level ID for garment

type

String

Required. aka category, format uses taxonomy utilized by Shopify, Meta/Facebook or Google. This must be as specific as possible, and contain information about the garment type, as in the above example.

price

String | Number

Required. Garment sale price

sizechart

String

Required. Name for size chart for this particular garment, ideally in <gender>_<garment type>_<sizing_dimensions> format. If the size chart name does not contain primary and secondary sizing dimensions, primaryDimension & secondaryDimensions are required parameters.

title

String

Required. Garment Name

variants

Array< Variant >

Required. A list of all available variants of the garment (eg, variants for all available sizes / colors / fits), below are all fields for variant

tags

Array < string >

Optional. A list of tags that correspond with the product, if available

description

String

Optional. Publicly viewable description of the garment

primaryDimension

'COLLAR'| 'OTHER'

Conditionally Required. Required if not available in size chart field. Optional otherwise.

secondaryDimensions

Array< 'INSEAM:NUMERIC'| 'INSEAM:ALPHA'| 'INSEAM:OTHER'| 'LENGTH:SLEEVE'| 'OTHER' >

Conditionally Required. Required if not available in size chart field. Optional otherwise.

Variant Object Contract Definition

Key

Type

Description

id

String | Number

Required. Variant ID

size

String

Required. Variant size

available

Boolean

Required. Boolean value corresponding to garment availability

description

String

Optional. If description differs from main product, please add it here

fit

String

Optional. If this garment has multiple fits on a single PDP (eg, slim, athletic, classic), include fit definition string of this particular variant.

sku

String | Number

If SKU/ID differ, SKU is required. Otherwise optional.

sizechart

String

If variant size chart differs from parent garment size chart, this is a required field. Otherwise, optional.

additionalMetadata

Object

Optional. Object for containing additional metadata as necessary -- consult with Bold Metrics implementation team about this object

Shopify Sites

<script>
    window._boldmetrics = {
        locale: "{{ shop.locale }}-{{ localization.country.iso_code }}",
        product: {{ product | json }}
    }
</script>

Soft Launch functionality

By default, before we officially launch, we have turned on softLaunch in the client configuration file for your site.

When softLaunch is active, this means that even if the Smart Size Chart JS tag is live on your site, and the Bold Metrics activator element is live, the Smart Size Chart will not be publicly visible on your site, but you will need to manually “flip a switch” using either a cookie or a specific query parameter in the URL of your PDPs to see the Smart Size Chart functioning as expected.

This allows for the following:

You, as a team, to integrate the various Bold Metrics scripts prior to completion of the integration process or prior to full SSC Button Design
Bold Metrics to test against live garment data in either a staging or production environment to ensure the experience will be working flawlessly for you and your customers
Bold Metrics and your team to work together to debug issues before we publicly “go live” and can flip the switch to activate the Smart Size Chart together!

In order to “turn on” the Smart Size Chart experience (ie, to see the SSC button as expected) while your site is in softLaunch mode, you will need to do utilize one of the following methods:

Query Parameter:
- If you’d just like to see the experience on a single product detail page, add the following query parameter to the URL you would like to see the Smart Size Chart experience on: ?bmiSoftLaunchOverride=1.
  - For instance, if your product detail page URL is http://www.threadchoice.com/index.html, you would update the url to be http://www.threadchoice.com/index.html?bmiSoftLaunchOverride=1
Cookie Override:
- If you are doing more extensive engineering work (or if the above method does not work due to URL rewrites or other issues), and would like to consistently have the experience live on a page until you turn it off, you can add the following cookie to your browser’s cookies: bmiSoftLaunchOverride=1
  - Generally, you can add a cookie to a site by running document.cookie=bmiSoftLaunchOverride=1 in the Web Developer console, or you can use some internal settings on your browser to set the cookie as active. Here’s some example instructions for Google Chrome: https://developer.chrome.com/docs/devtools/application/cookies/
  - This will have the softLaunch experience active until this cookie is removed, or until the Smart Size Chart is fully activated

Integrating 'Add To Cart' Functionality

The most effective way to ensure that a customer converts is by automatically selecting a size for them once the Smart Size Chart flow has ended. We provide a DOM event to listen to when size selection is complete. The bmi_add_to_cart event should be used to listen to the Call To Action button in the Smart Size Chart. The best practice is to add a small script to your PDP listening for the bmi_add_to_cart event that will select the correct size from your PDP when fired. An example implementation is below to provide general guidance -- your script on your PDP will be different. In this below example code block -- again, your PDP will be different:

there is an 'add to cart' button, with the id #add-to-cart:
the inner text is the size, eg, 'Medium'
all the available sizes are buttons, with the class name 'size-option'

EXAMPLE IMPLEMENTATION

NOTE: Do not copy and paste this in your site as is. This is meant to be an implementation guide to understand the flow, rather than a finished implementation.

<script>
  document.addEventListener("bmi_add_to_cart", e => {
    const { size } = e.detail; // This is the size the user selected
    // First: find the buttons corresponding to available sizes on my PDP
    const availableSizeButtons = document.getElementsByClassName('button.size-option'); 
   
  // Second: find the button corresponding with the size 
  // the user selected as well as the add to cart button

    const selectedItem = Array.from(availableSizeButtons).find(item => item.innerText.contai
  ns(size));

    const addToCartLink = document.getElementById('#add-to-cart');

    // Third: Pick the size the user selected in the SSC Flow
    if (selectedItem) {
      selectedItem.click();
    }

    // Last: add the selected size to cart
    if (addToCartLink) {
       setTimeout(() => addToCartLink.click(), 1500);
    }
</script>

Since every client's PDP is different, reach out to us if you are having trouble building this functionality -- we are happy to provide guidance and assistance!

Available DOM Events

bmi_reload

If you need to ‘force’ reload the Smart Size Chart due to new data being hydrated on the page, the below event can be run and the Smart Size Chart will reload. Here’s an example of a listener for this event:

function sendReloadEvent() {
    document.dispatchEvent(
        new CustomEvent('bmi_reload', {
            bubbles: true,
        })
    )
}

product_id_update

If you need to ‘force’ reload the Smart Size Chart due to new data being hydrated on the page, the below event can be run and the Smart Size Chart will reload. This is different from the bmi_reload event above in that you can pass a specific product_id with this event. Here’s an example of a listener for this event:

function sendProductUpdateEvent() {
    document.dispatchEvent(
        new CustomEvent('product_id_update', {
            bubbles: true,
            detail: {
                product_id: '<PRODUCT_ID>',
            },
        })
    )
}

Available DOM Event Listeners

Data Object in DOM Events
For certain DOM Events, we include an additional data object under the detail key:
fit: If a garment has fit information stored in our system, this indicator will be returned with this event.
sleeve: This is the sleeve measurement from the API call. This can also be found under the json object.
inventory: If our system recognizes inventory for your garments, inventory data will be returned.
json: This is the API response.
size: This is the user’s selected size.
userId: This is the Bold Metrics user ID.
selectedItem: This is the selected item (only used on the bmi_selected_item DOM Event). See bmi_selected_item for more information.

bmi_close

When the ‘X’ is clicked or a user clicks outside of the modal, the bmi_close event is fired. Here’s an example of a listener for this event:

document.addEventListener('bmi_close', () => {
    console.log('bmi_close');
});

bmi_recommendation_sent

The bmi_recommendation_sent event is fired immediately when the API responds with a recommendation. This event has an object attached with the recommendation.

For the data included in this DOM Event, see Data Object in DOM Events

Here’s an example of a listener for this event:

document.addEventListener("bmi_recommendation_sent", e => {
    console.log('bmi_recommendation_sent', e.detail);
});

bmi_selected_size

The bmi_selected_size event is fired when any size is selected on the recommendation screen. This immediately fires when the API response is returned with the recommended best size. This will subsequently fire on each size button click by the user.

For the data included in this DOM Event, see Data Object in DOM Events

Here’s an example of a listener for this event:

document.addEventListener("bmi_selected_size", e => {
    console.log('bmi_selected_size', e.detail);
});

bmi_add_to_cart

The bmi_add_to_cart event is fired when the CTA (call to action) button is clicked on the recommendation screen. This button might add the size to the cart, select the size without adding it to the cart, or simply do nothing. Regardless of the button action, this event will fire when clicked.

For the data included in this DOM Event, see Data Object in DOM Events

Here’s an example of a listener for this event:

document.addEventListener("bmi_add_to_cart", e => {
    console.log('bmi_add_to_cart', e.detail);
});

bmi_ssc_loaded

The bmi_ssc_loaded event is fired when the Bold Metrics Smart Size Chart (SSC) app has fully loaded and collected data on the PDP. This event only fires when the SSC successfully loads - if the SSC cannot load for whatever reason (missing or invalid product metadata, page rendering / blocking issues, unable to find Bold Metrics div), this event will not fire.

For the data included in this DOM Event, see Data Object in DOM Events

Here’s an example of a listener for this event:

document.addEventListener("bmi_ssc_loaded", e => {
    console.log('bmi_ssc_loaded', e.detail);
});

bmi_selected_item

The bmi_selected_item event is fired when the SSC flow has been completed, and the SSC has performed our best effort to match up a selected size with a given variant in the window._boldmetrics object. This event requires the following:

The window._boldmetrics object to be present on the PDP
An array of variant objects to be present in the window._boldmetrics object
Either a size key in the variant itself, or some identifying information in the variant (for Shopify sites, this is usually found in either the public_title / title or the name of the variant)

The event payload contains a data object with a selectedItem key under the detail object. The selecteditem object has the following values:

        {
          parentId //parent SKU or ID
          selectedSize //client selected size in Smart Size Chart
          recSelections //the entire 'rec selections' object
          fit //optional
          variants // all variants in bm object
          matchedToIndividualVariant // boolean, was a single matching variant found?
          matchingVariants // array, list of matching variants we filtered down to
        }

If we were able to match the user's selected size to a single matching variant:

matchedToIndividualVariant will be true
matchingVariants will be an array of size 1, with the matching variant present as an object in that list

This can be used to simplify the 'add to cart' flow or perform whatever user behavior you choose. For instance, if you are using Shopify, we recommend using Shopify's Cart API functionality (which is present on your Shopify PDPs) to get the variant ID and add it directly to cart. If we were not able to match the user's selected size to an individual variant (for instance, if there are multiple colors available, multiple fits or lengths available, or if we were not able to make a reliable prediction):

matchedToIndividualVariants will be false
matchingVariants may be an array of any size, with whatever variants we recognized might be a match

Here's an example of how you might use the bmi_selected_item event:

document.addEventListener("bmi_selected_item", e => {
    const { detail } = e;    
    const { selectedItem } = detail;

    if (selectedItem.matchedToIndividualVariant) {
        const selectedVariantId = matchingVariants[0].id;
        console.log('This variant was selected:', selectedVariantId);
    }  else {
        const allMatchingVariantIds = matchingVariants.map(variant => variant.id);
        console.log('All possible matching variants:', allMatchingVariantIds)
    }  
});

Frequently Asked Questions

Click the arrow on the left of each box to expand the answer.

I followed all the steps in the Quick Start guide, why doesn't the SSC show up on my site as expected?

There could be a few reasons this is happening.

Soft Launch is enabled by default before your account is live. This is to ensure that the Bold Metrics experience does not go live before it is fully ready. Toggle it on or off using the instructions here.
You may be using a staging site or test site that we do not know about. If you are currently using a sandbox environment or domain (such as localhost or a staging environment) and you are seeing errors to ssc/get-feed, we are not able to recognize the environment you are working in. Try using the following script to set the environment (replacing YOUR_CLIENT_ID with one from your Bold Metrics team)

if (!window.localStorage.getItem('boldMetricsStore')){ 
    window.localStorage.setItem(
        'boldMetricsStore', 
        JSON.stringify({ store: 'YOUR_CLIENT_ID' })
    ) 
}

We may not recognize the garment that the PDP is for. Ensure we have set the following: the window._boldmetrics object, the Bold Metrics div and any required data attributes on that element, and any additional instructions you may have received from your Bold Metrics team.
Confirm that you have one only instance of the Bold Metrics script, as well as only one Bold Metrics div on the page.

When clicking 'Add To Cart' in the Smart Size Chart experience, the garment does not add to a user's cart. Why is that?

Since every PDP is built differently, to have the best customer experience, we provide a number of different events that can be used at the end of the Smart Size Chart experience. You will need to follow the guides on either using the bmi_add_to_cart event or the bmi_selected_item event but the code must be customized by you for your existing PDP. We are happy to provide guidance and advice on writing code for these events!

Demo

PreviousCommon API Topics NextAnalytics Script

Last updated 7 months ago