Migration Guide: V2 to V3

This guide outlines the key technical differences between Smartfit Online Sizing V2 and V3, and provides a clear migration path with practical code examples.

---

Browser Compatibility

Smartfit Online Sizing V3 utilizes modern web technologies to provide an improved user experience.

JavaScript compatibility: The widget requires at least the browser versions listed below to function correctly. Users with older browsers may experience loading issues.

Browser	Minimum Version	Release Date
Chrome	94	Sep 22, 2021
Safari	16.4	Mar 27, 2023
Firefox	101	May 31, 2022

CSS compatibility: Visual styles may not render as intended if the browser version is older than those specified below.

Browser	Minimum Version	Release Date
Chrome	121	Jan 23, 2024
Safari	18.2	Dec 11, 2024
Firefox	117	Aug 29, 2023

• JavaScript ES2022
• JavaScript Mutation Observer
• JavaScript CSSStyleSheet constrcutor
• CSS Nesting
• CSS Backdrop Filter
• CSS Scrollbar-Width

Differences overview (V2 → V3)

Area	V2 (Legacy)	V3 (Current)	Impact
Status	Maintenance only	Actively supported	All new implementations should use V3
Widget types	geometries | sizing | ski | alternatives	product-sizing | geometry | category-sizing | banner | leasing	Expanded and more advanced widget options
Product types	bicycle (all widget types) ski (sizing only)	bicycle ski snowboard ski poles	Additional product types supported (more planned).
Smart Sizing Button	—	Result displayed in button without opening widget	Optional UX enhancement
Conversion tracking	Conversion widget	Removed	GA/GTM-based tracking will be available soon
Loader	Inline loader (widgets.onlinesizing.bike/loader.js), sets globals	ES module loader (widget3.smartfit.online)	No global OZ_CONFIG; modern, standards-based module loading
Embedding	Generic element with data-oz-*	Custom elements details	Declarative, semantic integration
Buttons	Default & custom	Predefined, custom (template-driven)	Dynamic labels and first-class fallback element
Button Labels	Default & custom	Default only	Button style is customizable in V3, but button text is not.
Callbacks	OZ_CONFIG.events.* (e.g., confirmSize)	DOM events (e.g., select) + attributes (e.g., onselect)	Transition to DOM custom events
Variant change	Custom V2 update function	Update element attributes via setAttribute	Native DOM workflow
Availability	Optional callback checkIsAvailable	From product feed only; no widget function	Update data pipeline; remove legacy callback
Reports	-	PDF	Comprehensive reports based on widget usage

---

General Migration Steps

Loader Script

V2

<script>
  ((win, doc, script, key, config, src) => {
    win["___OnlineSizing"] = key;
    win["___OnlineSizingConfig"] = config;
    const js = doc.createElement(script);
    js.id = key;
    js.src = src;
    js.async = true;

    const scripts = doc.getElementsByTagName(script);
    const lastScript = scripts[scripts.length - 1];
    lastScript.parentNode.insertBefore(js, lastScript);
  })(
    window,
    document,
    "script",
    "oz",
    OZ_CONFIG,
    "https://widgets.onlinesizing.bike/loader.js",
  );
</script>

V3

<script
  async
  type="module"
  src="https://widget3.smartfit.online/?apiKey={{ ADD YOUR API KEY }}"
></script>

Configuration

Configuration is no longer managed via a global object. Most settings are now managed in Smartfit Analytics at the API key level, and can be partially overridden per HTML element using attributes.

V3 Example

Default settings:

• lang: de
• style-name: light

<sf-product-sizing
  name="{{ title1 }}"
  global-id="{{ gtin1 }}"
  image="{{ imageUrl1 }}"
>
</sf-product-sizing>

<sf-product-sizing
  name="{{ title2 }}"
  global-id="{{ gtin2 }}"
  image="{{ imageUrl2 }}"
  lang="en"
  style-name="dark"
>
</sf-product-sizing>

Styles

Widget and button styles are now managed via a Style Configurator, accessible in Smartfit Analytics. At present, the configurator is not available for external users; style adjustments must be coordinated with our support team (email: support@smartfit.bike).

Updating Widget Configuration

V2

In V2, updateWidgetConfigurations must be called to apply configuration changes to the widget.

<div
  id="oz-button"
  data-oz-widget="sizing"
  data-oz-embed="launcher"
  data-oz-code="{{ product.ean }}"
  data-oz-name="{{ product.title }}"
  data-oz-image="{{ product.image.src }}"
  data-oz-price="{{ product.price }}"
></div>

<script>
  const sizingButton = document.getElementById("oz-button");
  if (sizingButton) {
    sizingButton.setAttribute(`data-${oz.namespace}-code`, "EANCODE");
    sizingButton.setAttribute(`data-${oz.namespace}-name`, "Bike Display Name");
    sizingButton.setAttribute(`data-${oz.namespace}-image`, "Image URL");

    oz.updateWidgetConfigurations([sizingButton]);
  }
</script>

V3

In V3, widgets automatically listen for attribute changes and update themselves accordingly.

<sf-product-sizing
  id="oz-button"
  name="{{ Product title variable }}"
  global-id="{{ GTIN variable }}"
  image="{{ Product image url }}"
>
</sf-product-sizing>

<script>
  const psButton = document.getElementById("oz-button");
  if (psButton) {
    psButton.setAttribute(`global-id`, "EANCODE");
    psButton.setAttribute(`name`, "Bike Display Name");
    psButton.setAttribute(`image`, "Image URL");
  }
</script>

Widget Types

V2

In V2, the widget type was specified using the data-oz-widget attribute.

<div data-oz-widget="geometries|sizing|ski|alternatives" ...></div>

V3

In V3, each widget type is represented by its own custom element:

<sf-product-sizing></sf-product-sizing>
<sf-geometry-display></sf-geometry-display>
<sf-category-sizing-button></sf-category-sizing-button>
<sf-category-sizing-banner></sf-category-sizing-banner>
<sf-product-leasing></sf-product-leasing>

Further Migration Steps

• Product Sizing
• Geometry Display
• Ski Sizing
• Recommendation
• Conversion