How products are matched to pages

The inline panel and the sticker need to know which product to show on the page they are placed on. This article explains how that resolution works and how to control it. The full testing report does not use matching; it always renders the product-id you give it.

Matching priority

The display resolves the product in this order, stopping at the first match:

1. product-id attribute. The Light Labs internal product ID. Most explicit, but you have to look it up and keep track of it yourself.

2. external-id attribute. Matched against the External IDs you have registered on your products in Light Labs. This can be any stable identifier you already own: your own product ID, your slug, a SKU, or a store variant ID.

3. URL slug. The display compares your product slugs against the current page URL and uses the product whose slug matches. When more than one slug matches, the longest match wins. Matching is case insensitive and the URL is decoded first.

If none of these resolve a product, the display renders nothing.

Standard product pages

On a normal product page, slug matching is usually all you need. Add the page's slug to the product in Light Labs and place the element. No attributes beyond company-id are required.

<lightlabs-widget company-id="YOUR_COMPANY_ID"></lightlabs-widget>

Landing, bundle, and collection pages

These pages do not carry a single product slug, so slug matching cannot pick a product. You have two ways to tell each panel which product to show.

Recommended: external IDs you already own

You are already rendering these pages from your own product data, so you already have an identifier for each item: your product ID, your slug, your SKU. Register that same identifier on the matching product in Light Labs, then pass it as external-id. You never have to look up or store a Light Labs ID.

Step 1. In Light Labs, add your identifier to the product's External IDs (see Setting External IDs below).

Step 2. On your page, loop over your own products and pass your identifier:

{products.map((product) => (
  <lightlabs-widget company-id="YOUR_COMPANY_ID" external-id={product.id} />
))}

Or with your slug, or any identifier you registered:

<lightlabs-widget company-id="YOUR_COMPANY_ID" external-id={product.slug} />

Each panel resolves on its own. Because the identifier is one you control, the mapping lives in your data, not in a separate lookup table you have to maintain against Light Labs.

Fallback: product-id

If you would rather not register external IDs, you can target each product by its Light Labs product-id, one element per product:

<lightlabs-widget company-id="YOUR_COMPANY_ID" product-id="42"></lightlabs-widget>
<lightlabs-widget company-id="YOUR_COMPANY_ID" product-id="43"></lightlabs-widget>

Find a product's ID in its URL in Light Labs. The tradeoff is that you have to look up each Light Labs ID and keep your own map of "my product to Light Labs product" up to date, which is why external IDs are usually the better choice.

Setting External IDs

External IDs live on a product's SKU in Light Labs:

1. Go to Products and open the product.

2. On the SKU, find the External IDs (optional) field.

3. Enter one or more identifiers, separated by commas, for example your product ID and your slug.

4. Save.

You can register more than one identifier per SKU, so the same product can be matched by your product ID and your slug. The same field also lets variants that share a formula map to one set of results.

Variants on a single product page

When a single product page sells multiple variants, use external-id to show the results for the selected variant. Set it to the variant identifier your store uses, for example a Shopify variant ID, and register that ID on the matching SKU.

<lightlabs-widget company-id="YOUR_COMPANY_ID" external-id="SHOPIFY_VARIANT_ID"></lightlabs-widget>

On Shopify you can render the current variant ID into the attribute, for example:

<lightlabs-widget
  company-id="YOUR_COMPANY_ID"
  external-id="{{ product.selected_or_first_available_variant.id }}"
></lightlabs-widget>

If the variant changes on the page without a full reload, update the attribute or call setExternalId. See 📄 Custom triggers and the JavaScript API. Updating external-id re-renders the display.

Configurators and single page builders

If a custom product builder shows several products on one URL with no per-product slug, slug matching will not work. Use the same external-id approach as bundle pages: register an identifier you own on each product, then render one element per item with external-id set to that identifier, updating it as the selection changes. Because these setups vary, email support@lightlabs.com and we will help you find the right pattern.