This guide walks through the technical steps of integrating the LumeCore SDK into a Shopify beauty store — from initial script placement through shade catalog configuration and multi-device testing. It's written for the developer handling the implementation, with enough context for a non-technical digital director to follow the logic.
Assumed starting point: a live Shopify store with an existing theme (Online Store 2.0 preferred, though the approach works with legacy themes), and a shade catalog with HEX color references for each applicable product variant.
How LumeCore integrates with Shopify: the architecture
LumeCore does not use Shopify's native AR capability — the .usdz / .glb model system built for 3D object placement via ARKit. That system is designed for viewing physical objects in space, which is a different use case from try-on overlays. LumeCore is a camera-based overlay SDK: it injects into the product page as a JavaScript embed and renders using the device camera and a WebGL canvas layer.
The integration has three components: (1) the SDK script tag, loaded conditionally on product pages only; (2) the shade catalog connector, which maps Shopify variant IDs to LumeCore shade references; and (3) the widget mount point, a DOM element in the product template where the try-on UI renders. All three are configured through a combination of theme.liquid edits and the LumeCore brand dashboard. No Shopify app installation is required, though an App Bridge 2.0 wrapper is available for brands who prefer managing configuration through the Shopify admin panel.
Step 1: place the SDK script in theme.liquid
Load the LumeCore SDK on product template pages only — not globally. Global loading adds weight to non-product pages (homepage, collection, blog, cart) where it provides no value.
In theme.liquid, near the closing </body> tag, add a conditional load:
{% if template.name == 'product' %}
<script
src="https://sdk.lumeglint.com/v1/lumecore.min.js"
data-lmg-key="{{ shop.metafields.lumeglint.api_key }}"
defer
></script>
{% endif %}Store the API key as a shop-level metafield (lumeglint.api_key) rather than hard-coding it in the template. This keeps it out of theme file version history and makes key rotation straightforward. Set the metafield via the Shopify Admin API or through the metafield editor in the Admin UI under Settings.
Step 2: add the widget mount point to the product template
In your product page section file — typically sections/main-product.liquid in an Online Store 2.0 theme — add the mount element adjacent to the add-to-cart button. Placement below the variant/shade selector and above the cart button performs best in usability testing:
{% if product.tags contains 'lmg-enabled' %}
<div
id="lmg-try-on-mount"
data-product-id="{{ product.id }}"
data-variant-id="{{ product.selected_or_first_available_variant.id }}"
>
</div>
{% endif %}Using a product tag (lmg-enabled) to gate the widget gives you granular control without template edits per product. Only tag products that have calibrated shade entries in the dashboard — a try-on button on an unconfigured product is worse than no button.
Step 3: configure the shade catalog in the dashboard
The LumeCore brand dashboard maps Shopify variant IDs to shade reference data. For each try-on-enabled variant, define four fields:
- HEX reference value. The base color of the shade. This should match the physical product — ideally from spectrophotometric measurement, not from product photography HEX values which carry ambient lighting bias.
- Finish type. Matte, satin, gloss, sheer, or metallic. The pipeline applies distinct blending and specular models per finish type.
- Product category. Lip, eye, complexion, or nail. Determines which face segmentation region the overlay targets.
- Opacity. 0.0–1.0 value representing the product's coverage at normal application. Full-coverage matte lip: ~0.85. Sheer tinted balm: 0.35–0.50.
Variant ID matching uses Shopify's Storefront API. When a shopper changes the shade in the variant picker, the widget reads the active variant ID from the page and retrieves the corresponding shade configuration. The catalog is cached client-side on first session load, so shade switching after initialization is near-instantaneous.
Step 4: synchronize variant selection
In Online Store 2.0 themes, variant changes dispatch a product:variant-change DOM event. LumeCore listens for this event by default — no additional code is required for standard themes.
For custom themes or headless storefronts using the Storefront API, trigger the variant update method manually:
// Call this wherever your variant picker updates
window.LumeCore.setVariant(variantId);setVariant() accepts a Shopify variant ID as integer or string. Call it in the same synchronous handler where you update the price display and add-to-cart form value — not as a separate async call — to keep page state consistent.
Step 5: test across device classes before enabling on live products
Three device classes to test before setting the lmg-enabled tag on production products:
iOS Safari on iPhone. LumeCore uses WebRTC camera access via getUserMedia. Safari on iOS 16.4+ supports this over HTTPS only — verify your store is not serving any mixed-content resources that could trigger a downgrade. Test on both an older device (iPhone 12 or equivalent) and a current model to catch WebGL performance variance across chip generations.
Android Chrome on a mid-range device. Not a flagship — a 2022 or 2023 mid-range Android represents a large share of your Android traffic and is where performance issues surface. Target Time to Interactive for the try-on session under 2.5 seconds on this device class. Anything above 3 seconds loses a meaningful share of sessions before the first shade renders.
Desktop Chrome or Firefox. Lower traffic share for beauty but non-trivial for research-phase browse sessions. Desktop webcam access works via the same API — verify the permission prompt appears correctly and that the widget is keyboard-accessible for accessibility compliance.
The three most common issues found during device testing: (1) HTTPS requirement not met on a staging subdomain, causing camera access to be silently denied; (2) variant ID mismatch due to a theme customization that changes how the active variant ID is surfaced to the DOM; (3) shade catalog entries with incorrect opacity values causing renders that look washed-out (opacity too low) or painted-on (opacity too high).
Connecting analytics events to your A/B framework
LumeCore emits JavaScript events that you can route to Google Analytics 4 or any analytics platform via the events API:
window.LumeCore.on('session:start', (data) => {
gtag('event', 'lmg_session_start', {
product_id: data.productId,
variant_id: data.variantId
});
});
window.LumeCore.on('session:end', (data) => {
gtag('event', 'lmg_session_end', {
shades_rendered: data.shadesRendered.length,
add_to_cart: data.addToCartClicked,
duration_ms: data.totalDurationMs
});
});The session:end event's addToCartClicked boolean is the core metric for measuring whether try-on sessions convert at a higher rate than non-try-on sessions — the conversion lift measurement described in the AR conversion post elsewhere on this site. To run this as a concurrent A/B test, you'll also need to record the variant assignment (try-on enabled vs. control) as a custom user property on the session, so you can segment by it in your analytics reporting.
The complete SDK reference, including all event names and payload schemas, is in the documentation at docs/api-reference. Integration support during your first setup is available via the Slack channel included in your trial onboarding email, or reach us directly at [email protected].