Skip to main content
Before rendering, virtual.fit matches the current page to a synced product. Configure one deterministic rule and test it with real storefront URLs.

​
Resolution modes

​
Path template

Use a path template when product routes have a consistent structure.
The token must match Match Products By. Use :handle when matching handles and :product_id when matching external product IDs.

​
Last path segment

Use this only when the final path segment is always the product handle or ID.
Avoid it if locale, variant, or campaign segments can appear after the product value.

​
Query parameter

Use this for routes that expose a stable product identifier in the query string.
Set Query Parameter Name to sku and match by Product ID.

​
Custom regex

Use a custom regular expression only when the standard modes cannot represent the route. The first capture group becomes the product hint.
Keep the expression anchored and narrow. A broad regex can accidentally match category, search, or account pages.

​
Test the rule

In virtual.fit’s Live URL Tester:
  1. Paste an absolute URL from the real storefront.
  2. Confirm the extracted value.
  3. Confirm the matched product title and ID.
  4. Confirm the message says the product is enabled.
Test at least:
  • A valid enabled product.
  • A valid disabled product.
  • An unknown product.
  • A collection or search page.
  • A localized route, if your storefront uses locales.

​
Manual product context

For SPAs, query-driven PDPs, or routes that cannot be expressed by a rule, call setProduct after initialization:
The id or handle must still identify a synced, enabled product. Manual context does not bypass its availability settings in virtual.fit. Call setProduct again after your router commits each new product page and whenever the selected variant changes.

​
Color and style variants

Keep one synced product ID for the product. Sync exact variants under it, including variant media when color, pattern, material, or style changes the garment.
variantId must match a source_variant_id synced under the product. variantImageUrl is a display hint; virtual.fit uses the canonical prepared media linked to the variant. Size-only variants usually share the product’s media. You can still send their variantId so availability and inventory refer to the exact purchasable combination.
Do not create duplicate product records for each color or size. One product with exact variants keeps recommendations product-level while still allowing virtual.fit to select the best in-stock visual variant.

​
Fail-closed behavior

The widget stays hidden when:
  • The rule extracts no value.
  • The value does not match a synced product.
  • The matched product is disabled.
  • The matched product has no usable garment images.
This is expected behavior. Do not add a fallback product unless every unmatched page should deliberately use that product.