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:

  1. Install a Private Shopify App for Bold Metrics Access For Garment Data Access

  2. Add the Smart Size Chart Script To Your PDPs

  3. Add the Bold Metrics div as well as the `window._boldmetrics` Object To Your PDPs

  4. 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

  1. Provide an initial set of garment data according to the instructions provided by your Bold Metrics representative.

  2. Provide an initial product feed for review

  3. Add the Smart Size Chart Script To Your PDPs

  4. Add the Bold Metrics div as well as the `window_boldmetrics` object to your PDPs

  5. 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>

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"
    ...
/>

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

Product Object Contract Definition

Variant Object Contract Definition

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 TopicsNextAnalytics Script

Last updated