SpreeAI Web SDK

The SpreeAI Web SDK is a JavaScript library that simplifies the integration of SpreeAI services into web applications. It provides tools to interact with SpreeAI APIs efficiently.

v2.0.0 introduces a new SDK shape: authenticate once with init(), then render any number of try-on or sizing buttons from the returned SDK. The legacy tryOnButton(...) API still works in v2 but is deprecated and will be removed in v3.0.0. See Migration from v1.

Installation

Install the package using npm or yarn:

npm install @spreeai/web-sdk
# or
yarn add @spreeai/web-sdk

Include the package as a script:

<script type="module" src="https://unpkg.com/@spreeai/web-sdk@2"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/@spreeai/web-sdk@2/dist/web-sdk.css"
/>

Quick Start

<div id="try-on-button"></div>
<div id="sizing-button"></div>

import { init } from "@spreeai/web-sdk";

const sdk = await init({
  clientId: "your-client-id",
  partnerId: "your-partner-id",
});

if (sdk) {
  // Render a try-on button for a single garment
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garmentId: "garment-123",
    enableAddToCart: true,
  });

  // Render a sizing recommendation button
  await sdk.renderSizingButton({
    elementId: "sizing-button",
    garmentId: "garment-123",
  });
}

Features

• Virtual Try-On: Render a button that opens a virtual try-on experience for a garment.
• Multi-garment outfits: Try on multiple garments together using the new garments array API. Outfits are validated server-side; falls back to the first garment if no matching outfit is available.
• Variant matching: Pass color, fit, gender, or style per garment to pin a specific variant.
• Sizing recommendations: Render a sizing button that opens a size-recommendation flow and caches the result.
• Add-to-Cart Integration: Optional add-to-cart callback wired to the iframe.
• Customizable UI: Extensive styling for the try-on button.
• Loading Screen Customization: Configure custom loading videos and rotating text.

API Reference

init(options)

Authenticates with the SpreeAI API and returns an SDK object. Returns null if authentication fails.

const sdk = await init({
  clientId: string,
  partnerId: string,
  baseURL?: string,    // default: "https://protea-bridge.spreeai.com"
  baseApiURL?: string, // default: "https://api.spreeai.com"
});

The returned SDK exposes:

interface SpreeAISDK {
  renderTryOnButton(options: RenderTryOnButtonOptions): Promise<void>;
  renderSizingButton(
    options: RenderSizingButtonOptions
  ): Promise<SizingButtonResult | undefined>;
}

sdk.renderTryOnButton(options)

Renders a try-on button into the element identified by elementId.

Required

• elementId (string): The id of the host element.
• One of:
  • garments (GarmentInput[]): Array of garments to try on. Multi-garment requests are validated as an outfit on the server; if no matching outfit is found, the SDK falls back to the first garment.
  • garmentId (string, deprecated): Single garment id. Use garments instead.

Optional

• className (string): Extra CSS class on the button element.
• button.text (string): Button label. Default: "Try It On" for a single garment, "Try this look" for multiple garments. Overridden by features.tryOnButton.text.
• enableAddToCart (boolean): Enable add-to-cart inside the iframe. Default: false.
• features.loadingScreen: { videoUrl?: string; loadingText?: string[] } — loadingText must be 2–5 entries of ≤ 42 chars each; invalid values are dropped with a console warning.
• features.tryOnButton: Styling and content overrides — text, iconUrl, iconHeight, backgroundColor, textColor, width, height, fontSize, fontWeight, padding, border, borderRadius, boxShadow.
• events.onTryOnButtonClick(event): Called on button click before the dialog opens.
• events.onAddToCartClicked(event): Called when the iframe posts an add-to-cart message. See Events below.
• variant (VariantOptions, deprecated): Legacy single-garment variant filter. Use garments[i].variant instead.

GarmentInput

interface GarmentInput {
  garmentId: string;
  variant?: {
    color?: string;
    fit?: string;
    gender?: string;
    style?: string;
  };
}

If variant is supplied, the matching variant on the garment must exist and be available, or the call exits with an error.

sdk.renderSizingButton(options)

Renders a sizing-recommendation button into elementId. The recommended size is cached in localStorage per garment.

await sdk.renderSizingButton({
  elementId: string,
  garmentId: string,
});

Returns { recommendedSize: string | undefined } — populated from cache on subsequent loads.

Events

onTryOnButtonClick

Fired when the user clicks the try-on button (before the dialog opens).

{
  name: "spreeai-try-on-button-clicked";
}

onAddToCartClicked

Fired when the iframe posts an add-to-cart message. Requires enableAddToCart: true.

{
  name: "spreeai-add-to-cart-clicked",
  garments: Garment[],          // garments the user wants to add
  setIsLoading: (loading: boolean) => void,
  closePopUp: () => void,
  onError: (message: string) => void,
}

events: {
  onAddToCartClicked: async ({ garments, setIsLoading, closePopUp, onError }) => {
    setIsLoading(true);
    try {
      await fetch("/api/cart", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ ids: garments.map(g => g.id) }),
      });
      setIsLoading(false);
      closePopUp();
    } catch (err) {
      setIsLoading(false);
      onError("Failed to add to cart. Please try again.");
    }
  },
}

Complete Example

import { init } from "@spreeai/web-sdk";

const sdk = await init({
  clientId: "f3267114-9b01-0000-0100-b23099d74e92",
  partnerId: "my-brand",
});

if (sdk) {
  await sdk.renderTryOnButton({
    elementId: "try-on-button",
    garments: [
      { garmentId: "shirt-123", variant: { color: "blue", fit: "regular" } },
      { garmentId: "pants-456", variant: { color: "indigo" } },
    ],
    enableAddToCart: true,
    events: {
      onTryOnButtonClick: event => analytics.track("try_on_started", event),
      onAddToCartClicked: async ({
        garments,
        setIsLoading,
        closePopUp,
        onError,
      }) => {
        setIsLoading(true);
        try {
          await fetch("/api/cart/add", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ ids: garments.map(g => g.id) }),
          });
          setIsLoading(false);
          closePopUp();
        } catch (err) {
          setIsLoading(false);
          onError(err.message);
        }
      },
    },
    features: {
      loadingScreen: {
        videoUrl: "https://cdn.example.com/loading.mp4",
        loadingText: [
          "Preparing your fitting room…",
          "Loading models…",
          "Almost ready!",
        ],
      },
      tryOnButton: {
        backgroundColor: "#000",
        textColor: "#fff",
        borderRadius: "4px",
        fontSize: "14px",
        padding: "10px 20px",
      },
    },
  });
}

Migration from v1

v1's single tryOnButton({...}) call is replaced by an init() step plus an SDK method per button. The auth handshake now happens once instead of per-button.

// v1 (deprecated — emits a console warning on first call, removed in v3.0.0)
import { tryOnButton } from "@spreeai/web-sdk";
await tryOnButton({
  clientId,
  partnerId,
  elementId: "try-on-button",
  garmentId: "garment-123",
  events,
  features,
});

// v2
import { init } from "@spreeai/web-sdk";
const sdk = await init({ clientId, partnerId });
await sdk?.renderTryOnButton({
  elementId: "try-on-button",
  garmentId: "garment-123",
  events,
  features,
});

events, features, className, button, and enableAddToCart carry over with the same shape. The onAddToCartClicked event payload now exposes garments (array) instead of a single garment to support multi-garment outfits.

Legacy tryOnButton (deprecated)

The v1 entry point still works in 2.x:

import { tryOnButton } from "@spreeai/web-sdk";

The first call logs a deprecation warning. It will be removed in v3.0.0.

TypeScript Support

The SDK is written in TypeScript and ships full type definitions:

import {
  init,
  type SpreeAISDK,
  type RenderTryOnButtonOptions,
  type GarmentInput,
  type AddToCartClickedEvent,
} from "@spreeai/web-sdk";

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For questions or support, contact [email protected].