@cuvara/retailer-sdk

JavaScript SDK for embedding Cuvara Try On on retailer product pages.

The SDK confirms the product against the public retailer API, shows a Try It On You button only when the product is valid, and opens the Cuvara try-on experience in a modal iframe.

Install

npm install @cuvara/retailer-sdk

Or load the IIFE build from your CDN / static hosting:

<script src="https://cdn.example.com/cuvara-retailer-sdk.iife.js"></script>

Prerequisites

1. Create a retailer API token (rtk_...) in the Cuvara admin.
2. Catalog products with external_id values that match your storefront product IDs.
3. Know your API base URL (including /api/v1) and Cuvara frontend URL.

Vanilla JavaScript

<div id="cuvara-try-on"></div>
<script type="module">
  import { Cuvara } from '@cuvara/retailer-sdk'

  Cuvara.init({
    token: 'rtk_...',
    apiBaseUrl: 'https://api.example.com/api/v1',
    frontendUrl: 'https://app.example.com',
  })

  const handle = Cuvara.mount('#cuvara-try-on', {
    externalId: 'product-sku-123',
    onError: (error) => console.warn('[Cuvara]', error),
  })

  // handle.destroy()
</script>

With the IIFE build:

<div id="cuvara-try-on"></div>
<script src="/cuvara-retailer-sdk.iife.js"></script>
<script>
  Cuvara.init({
    token: 'rtk_...',
    apiBaseUrl: 'https://api.example.com/api/v1',
    frontendUrl: 'https://app.example.com',
  })
  Cuvara.mount('#cuvara-try-on', {
    externalId: 'product-sku-123',
    onError: (error) => console.warn('[Cuvara]', error),
  })
</script>

React

import { CuvaraProvider, CuvaraTryOnButton } from '@cuvara/retailer-sdk/react'

export function ProductPage({ product }) {
  return (
    <CuvaraProvider
      token="rtk_..."
      apiBaseUrl="https://api.example.com/api/v1"
      frontendUrl="https://app.example.com"
    >
      <CuvaraTryOnButton
        externalId={product.id}
        onError={(error) => console.warn('[Cuvara]', error)}
      />
    </CuvaraProvider>
  )
}

Vue

<script setup lang="ts">
import { CuvaraProvider, CuvaraTryOnButton } from '@cuvara/retailer-sdk/vue'
</script>

<template>
  <CuvaraProvider
    :token="token"
    :api-base-url="apiBaseUrl"
    :frontend-url="frontendUrl"
  >
    <CuvaraTryOnButton
      :external-id="product.id"
      @error="(error) => console.warn('[Cuvara]', error)"
    />
  </CuvaraProvider>
</template>

Shopify public app / theme snippet

Pass the storefront product id explicitly (Liquid product.id, or your mapped external id):

<div id="cuvara-try-on"></div>
<script src="https://cdn.example.com/cuvara-retailer-sdk.iife.js"></script>
<script>
  Cuvara.init({
    token: 'rtk_...',
    apiBaseUrl: 'https://api.example.com/api/v1',
    frontendUrl: 'https://app.example.com',
  })
  Cuvara.mount('#cuvara-try-on', {
    externalId: '{{ product.id }}',
    onError: (error) => console.warn('[Cuvara]', error),
  })
</script>

Behavior

1. Cuvara.init stores the retailer token and URLs.
2. Cuvara.mount calls POST /retailers/public/confirm with Authorization: Bearer rtk_… and { external_id }.
3. On 200, the Try On button is rendered into the target element. A hidden iframe loads {frontendUrl}/retailers/embed-session and, if the shopper already has a Cuvara session, the promo shows that account:
   • Guest Account with the creation date
   • Guest accounts that already entered a name but have not confirmed email: name (and avatar thumb if present) plus a prompt to check their inbox — they are still a Guest Account until confirmation
   • Regular accounts with first and last name, plus an avatar thumbnail when one is active
   • A Logoff control (with confirmation — stronger copy for guest accounts, which cannot be recovered and are auto-deleted after 30 days)
4. On 401 / 403 / 404 / network error, the target stays empty, except a region block (This App is not supported in …), which replaces the Try On button with that message. Failures are logged with console.warn('[Cuvara]', error) and the optional onError callback.
5. On click, a modal iframe opens {frontendUrl}/retailers/try-on?externalId=…. The retailer token is passed to the iframe with postMessage, not the URL. Closing the modal refreshes the promo identity.

Mount options

| Option | Type | Description | |---|---|---| | externalId | string | Required. Must match Product.external_id in Cuvara. | | label | string | Button label. Defaults to Try It On You. | | className | string | Extra class on the root wrapper. | | onConfirm | (response) => void | Fired after a successful confirm. | | onError | (error) => void | Fired when confirm fails. The shopper still sees no button, except for a region-unsupported message in the button area. | | onOpen / onClose | () => void | Modal lifecycle. |

Theming

Pass theme to Cuvara.mount (or <CuvaraTryOnButton theme={...} />). Values are set as CSS variables on .cuvara-root. Omit a key to keep the default.

Cuvara.mount('#try-on', {
  externalId: 'sku-1',
  theme: {
    accent: '#111',
    accentHover: '#333',
    surface: '#f7f7f7',
    text: '#111',
    muted: '#6b7280',
    border: '#f3f4f6',
    white: '#fff',
    fontFamily: 'Georgia, serif',
  },
})

You can also override the same variables in CSS:

.cuvara-root {
  --cuvara-accent: #111;
  --cuvara-accent-hover: #333;
}

Builds

• dist/cuvara-retailer-sdk.js (ESM)
• dist/cuvara-retailer-sdk.iife.js (script tag / Shopify)
• dist/react/index.js, dist/vue/index.js
• Type declarations under dist/