@vitraun/webar

Web Component package for Vitraun Virtual Try-On (<vitraun-vto>), distributed as npm + CDN bundle.

Install (npm)

npm i @vitraun/webar

import '@vitraun/webar'

// In React / TSX you can write `auto-open={true}` (no spread needed).

<vitraun-vto
  merchant-id="vtrn-mch-key-..."
  widget-id="vtrn-wdg-key-..."
  lang="en"
  auto-open
></vitraun-vto>

Try-On app origin (data-base-url) is baked into the published bundle from constants/default-widget-base-url.js (default dev app origin). Retailers do not need to set it. Use **data-base-url** only to override (staging, self-hosted). Rebuild with VITRAUN_WIDGET_EMBEDDED_BASE_URL=<origin> when the default dev host is wrong for your setup.

The widget script itself should be loaded from your CDN, from jsDelivr (mirror npm), or via import '@vitraun/webar' — not from the Try-On Next.js app.

jsDelivr (@vitraun/webar only)

After npm publish of @vitraun/webar, files under dist/ are available on jsDelivr (paths match the tarball):

https://cdn.jsdelivr.net/npm/@vitraun/webar@<version>/dist/widget.min.js
https://cdn.jsdelivr.net/npm/@vitraun/webar@<version>/dist/events.min.js

Example (<version> = published semver, e.g. 0.1.2):

<script src="https://cdn.jsdelivr.net/npm/@vitraun/[email protected]/dist/widget.min.js"></script>
<script type="module">
  import { subscribeVitraunVTOEvents } from 'https://cdn.jsdelivr.net/npm/@vitraun/[email protected]/dist/events.min.js'
</script>

The package.json field jsdelivr points to dist/widget.min.js so the default short URL https://cdn.jsdelivr.net/npm/@vitraun/webar resolves to the widget bundle when supported by jsDelivr.

Optional attribute **auto-open**: when present (or auto-open="true"), the element calls open() after it connects, so hosts do not need a useLayoutEffect or script callback.

Optional attribute **console**: when true, the widget shows an Events console button that opens a modal with captured Try-On events.

Events and logs helpers

The package exports helpers to capture widget events consistently:

import {
  VITRAUN_VTO_DEFAULT_EVENT_TYPES,
  subscribeVitraunVTOEvents,
} from '@vitraun/webar'

const dispose = subscribeVitraunVTOEvents(containerElement, (entry) => {
  console.log(entry.type, entry.timestamp, entry.detail)
})

// later:
dispose()

By default it listens to: addToCart, removeFromCart, redirectToCart, and analysisFinished. You can opt in to statusChange and vtoUsage using options, or pass a custom eventTypes list.

For React consumers, the package also provides a hook:

import { useVitraunVTOEventLogs } from '@vitraun/webar/react'

const { events, clearEvents } = useVitraunVTOEventLogs(containerRef.current)

Use via CDN (HTML puro)

Publish dist/widget.min.js and dist/widget-runtime.min.js to your CDN after each release (S3 + CloudFront, R2, etc.). This repo ships an AWS S3 helper that uses the AWS CLI:

npm run build
export VITRAUN_CDN_UPLOAD=1
export VITRAUN_CDN_S3_BUCKET=your-bucket-name
npm run deploy:cdn

See config/cdn-upload.env.example for all variables (optional root prefix, dry-run, region).

<script src="https://cdn.example.com/@vitraun/[email protected]/dist/widget.min.js"></script>
<vitraun-vto
  merchant-id="vtrn-mch-key-..."
  widget-id="vtrn-wdg-key-..."
  lang="en"
></vitraun-vto>
<script>
  document.querySelector('vitraun-vto')?.open()
</script>