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
| Mode | Example URL | Configuration | Extracted value |
|---|
| Path template | /products/linen-dress | /products/:handle | linen-dress |
| Last path segment | /collections/summer/linen-dress | Match by handle | linen-dress |
| Query parameter | /product?sku=sku-10042 | Parameter sku, match by product ID | sku-10042 |
| Custom regex | /shop/item/linen-dress | ^/shop/item/([^/]+)$ | First capture group |
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:
- Paste an absolute URL from the real storefront.
- Confirm the extracted value.
- Confirm the matched product title and ID.
- 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.
Color and style variants
When variants use different garments or colors, sync each one with its own external product ID. Pass the selected variant’s synced ID when the shopper changes variants.
imageUrl provides the media shown in the storefront context. It does not replace the garment associated with the synced product ID. Reusing one ID while changing only imageUrl continues to use that ID’s prepared garment.
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. 
