[How to] Configure VTO Native Frame Carousel?

Prerequisites

Before integrating the Native Frame Carousel, ensure that:

• Virtual Try-on is already integrated and working on your site.

• You have access to:

  • Frame identifiers

  • Frame images and variant assets (thumbnails, lens images)

Integration overview

The Native Frame Carousel is composed of two sections:

• A "Recommendation section", that shows the photocollection and name of frame models.
• A "Variant section", that shows the combination of icons and labels for the different color and size variants.

The Native Frame Carousel is configured through an instanciation parameter.

The configuration consists of:

• A list of frame models (min 1, max 6).

  • If more than one frame model is provided, the "Recommended section" will be displayed with the models' information (see layouting)

• A list of color and size variants, for each frame model (optional, unlimited).

  • If more than one variant is provided (for the current model), the "Variant section" will be displayed with the variants' information (see layouting)

• A list of lens tints (optional).

• Customization for the carousel UI (optional).

The carousel is rendered natively by the VTO. No additional UI implementation is required on your side.

Add the Native Frame Carousel configuration

Include the Native Frame Carousel configuration when initializing the VTO.

• carousel

Configuration structure

All sections are optional, but each item inside them must respect required fields to be displayed.

Configure frame models

If more than one frame model is provided, they are displayed in the dedicated "Recommendation section" inside the VTO.

Rules

• Maximum 6 frame models

• All required fields must be provided

• Frame models with missing required fields will not be displayed

Required fields

• frameLabel : the displayed name of the frame model (e.g. "my 

• frameImageUrl : the displayed photocollection of the frame model

• variants : the list of color variants for the frame model

Optional fields

• frameAdditionalInfo : an optional additional displayed label (such as a brand or a marketing tag) 

frames: [
  {
    frameLabel: 'string',
    frameImageUrl: 'string',
    frameAdditionalInfo: 'string',
    variants: [ 
      sizes: [
        {
          frameId: 'string'
        }
      ] 
    ]
  }
]

Frame variants allow users to switch between different versions of the same frame model.

A variant is defined as a color variant with size variant itself.

You can choose to provide one or multiple color variants, with one or multiple size variants each.

Color variants

Required fields

• variantLabel : the displayed name of the color variant (e.g. "Clear" or "Blue")

• variantThumbnailUrl : the displayed icon to pick the color variant

• sizes : the list of sizes for the variant of the frame model

{
    variantLabel: 'string',
    variantThumbnailUrl: 'string',
    sizes: [{ frameId: 'string' }],
}

Required fields

• frameId : the identifier for the variant of the frame model (a SKU, UPC or EAN)

• sizeLabel : the displayed name of the size (e.g. "Medium" or "54mm")

{
    sizeLabel: 'string',
    frameId: 'string',
}

Required fields

• lensId : the identifier for the lens tint (a SKU)

• lensImageUrl : the displayed icon to pick the lens tint

• lensLabel : the displayed name of the lens tint (e.g. "Ocean blue")

lenses: [
    {
        lensId: 'string',
        lensImageUrl: 'string',
        lensLabel: 'string'
    }
]

You can change the title of the “Recommended section" according to your needs.

settings: {
   recommendedSectionTitle : 'string'
}

If not provided, default text “You might also like” is displayed.

Error handling and validation

• If a required field is missing, the corresponding frame model is not displayed.

• If more than 6 frame models are provided, additional models are ignored.

It is recommended to validate all required fields before deploying to production.

Final checklist before go-live

• VTO integration working correctly

• All required fields provided for frames and variants

• Image URLs publicly accessible

• Frame models limited to 6 items

Example

Follow this codepen example!