shopar-plugin/dist/shopar-plugin.d.ts

Plugin for the Web that seamlessly integrates into your webpage to create embedded virtual try-on and 3D preview capabilities.

declare const strings_: {
    'loading.ar': string;
    'loading.3d': string;
};
type Strings = typeof strings_;

/** Preview state values. */
declare const PREVIEW_STATES: readonly ["AR", "3D"];
/** Preview state type. */
type PreviewState = typeof PREVIEW_STATES[number];
/**
 * Configuration of an animation key frame at the specified time point.
 */
type KeyFrameConfig = {
    /** Timestamp (in ms). */
    time: number;
    /** Vertical angle of rotation (in degrees). */
    pitch?: number;
    /** Horizontal angle of rotation (in degrees). */
    yaw?: number;
    /** Camera's field of view (in degrees). */
    fov?: number;
    /**
     * Easing function used for interpolating the values between this and the next key frame.
     *
     * Supported options are:
     * - `'hold'`: maintain the current value without interpolation.
     * - `'linear'`: linear interpolation.
     * - `'sine'`: sine wave interpolation.
     * - `'ease'`: starts slowly, accelerates sharply and slows gradually towards the end.
     * - `'ease-in'`: starts slowly, progressively speeds up until the end, at which point it stops abruptly.
     * - `'ease-out'`: starts abruptly and progressively slows down towards the end.
     * - `'ease-in-out'`: smooth start and end with gradual acceleration and decceleration.
     *
     * Additionally, it's possible to specify a custom Bézier function:
     * - `'cubic-bezier(x1, y1, x2, y2)'`: define two 2D points for a custom interpolation curve.
     *
     * @default 'ease-in-out'
     */
    interpolation?: string;
};
/**
 * Options used for the plugin setup.
 */
type SetupOptions = {
    /** API key found in the ShopAR dashboard. */
    apiKey: string;
    /** Product identifier. */
    sku: string;
    /**
     * The element to inflate with ShopAR UI.
     *
     * @remarks If using default UI, its CSS position property must be either 'static' or 'relative'.
     */
    targetElement: HTMLElement;
    /**
     * If provided, defines which preview type the plugin initializes to.
     */
    initialState?: PreviewState;
    /**
     * If provided, defines where the additional ShopAR plugin files are fetched from.
     *
     * @default `https://cdn.jsdelivr.net/npm/shopar-plugin@${version}/`
     */
    baseUrl?: string;
    /**
     * If provided and set to `false`, disables the default UI such as buttons, loading and error views.
     *
     * When the default UI is disabled, use the returned object as a controller:
     * ```js
     * const shopAR = await ShopAR.plugin.setup({
     *   // ...
     *   defaultUI: false,
     * });
     * shopAR.launchAR();
     * ```
     *
     * @default true
     */
    defaultUI?: boolean;
    /**
     * If provided and set to `false`, disables user interactivity by ignoring input events.
     *
     * @default true
     */
    interactive?: boolean;
    /**
     * If provided, the corresponding touch scroll behavior will be used in 3D.
     *
     * Supported values are:
     * - `none`: Touch gestures are never interpreted as scrolling. This might be useful if 3D occupies the whole viewport.
     * - `pan-x`: Touch gestures that start horizontally are interpreted as scrolling.
     * - `pan-y`: Touch gestures that start vertically are interpreted as scrolling.
     *
     * @default 'pan-y'
     */
    touchAction?: 'none' | 'pan-x' | 'pan-y';
    /**
     * If provided and set to `false`, disables zoom in 3D by ignoring mouse scroll or pinch touch events.
     *
     * @default true
     */
    zoomEnabled?: boolean;
    /**
     * If provided, it will be used as the minimum zoom level in 3D.
     *
     * @default 0.625
     */
    minZoom?: number;
    /**
     * If provided, it will be used as the maximum zoom level in 3D.
     *
     * @default 5
     */
    maxZoom?: number;
    /**
     * If provided and set to `true`, transparent background will always be used in 3D.
     *
     * This overrides the default behaviour which uses the transparent background only for models **without** transmissive materials.
     *
     * WARNING:
     * Opaque background is intentionally used for models with transmission to avoid the associated rendering issues.
     * When using this feature, please make sure that the transmissive parts of the model look as desired.
     *
     * @default false
     */
    alwaysTransparentBackground?: boolean;
    strings?: Strings;
    /**
     * If provided, replaces the default interactivity animation in 3D with a custom one.
     *
     * Two formats are supported: `KeyFrameConfig[]` and `string`.
     * For more information on the `KeyFrameConfig[]` format, see {@link KeyFrameConfig}.
     *
     * The `string` format is interpreted as a plain-text table. Empty lines and comments are ignored.
     * First line defines the columns and all subsequent lines define data per key frame.
     *
     * Supported columns are:
     * - `time`: timestamp of the key frame.
     * - `pitch`: vertical angle of rotation.
     * - `yaw`: horizontal angle of rotation.
     * - `fov`: camera's field of view.
     * - `interpolation`: easing function used for interpolating the values between this and the next key frame.
     * See {@link KeyFrameConfig.interpolation} for supported options.
     *
     * Timestamps are specified with or without a unit (`ms` or `s`). When not specified, milliseconds are used.
     *
     * Angles are specified with or without a unit (`deg` or `rad`). When not specified, degrees are used.
     *
     * @example
     * `
     * # Empty lines and comments are ignored.
     *
     * time pitch yaw    fov   interpolation
     * 0s   45deg 60deg  25deg hold
     * 1s   45deg 60deg  25deg ease-in-out
     * 2s   60deg -60deg 20deg hold
     * 3s   60deg -60deg 20deg ease-in-out
     * 4s   90deg 90deg  40deg hold
     * 5s   90deg 90deg  40deg ease-in-out
     * 6s   45deg 420deg 25deg hold
     * `
     *
     * @example
     * [
     *   { time: 0,    pitch: 45, yaw: 60,  fov: 25, interpolation: 'hold' },
     *   { time: 1000, pitch: 45, yaw: 60,  fov: 25, interpolation: 'ease-in-out' },
     *   { time: 2000, pitch: 60, yaw: -60, fov: 20, interpolation: 'hold' },
     *   { time: 3000, pitch: 60, yaw: -60, fov: 20, interpolation: 'ease-in-out' },
     *   { time: 4000, pitch: 90, yaw: 90,  fov: 40, interpolation: 'hold' },
     *   { time: 5000, pitch: 90, yaw: 90,  fov: 40, interpolation: 'ease-in-out' },
     *   { time: 6000, pitch: 45, yaw: 420, fov: 25, interpolation: 'hold' },
     * ]
     */
    initialAnimation?: KeyFrameConfig[] | string;
    _internalOptions?: any;
};
/**
 * Options used for the vision plugin setup.
 */
type VisionOptions = {
    /** API key found in the ShopAR dashboard. */
    apiKey: string;
    /**
     * The element to inflate with camera canvas.
     */
    targetElement: HTMLElement;
    /**
     * If provided, defines where the additional ShopAR plugin files are fetched from.
     *
     * @default `https://cdn.jsdelivr.net/npm/shopar-plugin@${version}/`
     */
    baseUrl?: string;
};

/**
 * Truescale output measurements
 */
type FaceMeasurement = {
    /**
     * Face width in millimeters.
     */
    faceWidth: number;
    /**
     * Interpupillary distance in millimeters.
     */
    IPD: number;
};
/**
 * Type that wraps face position and orientation.
 */
type FacePose = {
    /**
     * Face position in uncalibrated 3D space.
     */
    translation: number[];
    /**
     * Face rotation represented as Tait-Bryan angles (nautical angles).
     *
     * Sequence of fields in this array is yaw, pitch, roll (heading, elevation, bank).
     */
    rotation: number[];
};
/**
 * Plugin controller.
 */
type Plugin = {
    /**
     * Launches the AR view.
     * Set to `undefined` if AR is not supported for given SKU.
     *
     * @returns A promise that resolves when AR is launched.
     */
    launchAR?: () => Promise<void>;
    /**
     * Launches the 3D view.
     * Set to `undefined` if 3D is not supported for given SKU.
     *
     * @returns A promise that resolves when 3D is launched.
     */
    launch3D?: () => Promise<void>;
    /**
     * Closes the AR view.
     * Set to `undefined` if AR is not supported for given SKU.
     *
     * @returns A promise that resolves when AR is closed.
     */
    closeAR?: () => Promise<void>;
    /**
     * Closes the 3D view.
     * Set to `undefined` if 3D is not supported for given SKU.
     *
     * @returns A promise that resolves when 3D is closed.
     */
    close3D?: () => Promise<void>;
    /**
     * Closes the AR or 3D view.
     * Set to `undefined` if neither AR nor 3D are supported for given SKU.
     *
     * @returns A promise that resolves when AR or 3D is closed.
     */
    close?: () => Promise<void>;
    /**
     * Returns the current user interactivity value.
     *
     * @returns `true` is user interactivity is enabled and `false` otherwise.
     */
    isInteractive: () => boolean;
    /**
     * Sets user interactivity to the provided value. Set to `false` to ignore input events.
     *
     * @param value The provided value.
     */
    setInteractive: (interactive: boolean) => void;
};
declare class PluginError extends Error {
    constructor(message: string);
}
/**
 * Vision plugin controller
 */
type VisionPlugin = {
    /**
     * Register a face pose callback which will be called if face is detected.
     */
    registerFacePoseListener?: (facePoseListener: (facePose: FacePose) => void) => void;
    /**
     * Register a face measurement callback which will be called if face is detected.
     */
    registerFaceMeasurementListener?: (faceMeasurementListener: (faceMeasurement: FaceMeasurement) => void) => void;
    /**
     * Switch the AR effect for preview
     *
     * This call is a thin wrapper around DeepAR.switchEffect API.
     *
     * @param arUrl A path to the AR effect file
     * @returns Promise that resolves when an effect start rendering
     */
    switchEffect?: (arUrl: string) => Promise<void>;
    /**
     * Clear the AR effect
     *
     * Call this after switchEffect to clear the loaded effect.
     * @returns void
     */
    clearEffect?: () => void;
    /**
     * Closes the vision plugin and releases the camera.
     *
     * @returns A promise that resolves when AR is closed.
     */
    close?: () => void;
};

/**
 * ShopAR vision plugin.
 *
 * @example
 * Using CDN:
 * ```html
 * <script src="../../shopar-plugin/shopar-plugin.js"></script>
 * <script>
 *   const vision = ShopAR.vision.setup({ ... });
 * </script>
 * ```
 *
 * @example
 * Using a module bundler:
 * ```js
 * import { ShopAR } from 'shopar-plugin';
 *
 * const vision = ShopAR.vision.setup({ ... });
 * ```
 */
declare const vision: {
    /**
     * Initializes vision modules and renderes deepar canvas.
     *
     * If successful, function returns a handle to the VisionPlugin. This component alows for lower level control
     * over DeepAR and truescale components.
     *
     * @param options Setup options.
     */
    setup: (options: VisionOptions) => Promise<VisionPlugin>;
};
/**
 * The ShopAR plugin.
 *
 * @example
 * Using CDN:
 * ```html
 * <script src="../../shopar-plugin/shopar-plugin.js"></script>
 * <script>
 *   ShopAR.plugin.setup({ ... });
 * </script>
 * ```
 *
 * @example
 * Using a module bundler:
 * ```js
 * import { ShopAR } from 'shopar-plugin';
 *
 * ShopAR.plugin.setup({ ... });
 * ```
 */
declare const plugin: {
    /**
     * Fetches the specified product from the ShopAR dashboard and renders the ShopAR UI.
     *
     * @param options Setup options.
     */
    setup: (options: SetupOptions) => Promise<Plugin>;
    /** Plugin version. */
    version: string;
};

export { type FaceMeasurement, type FacePose, type KeyFrameConfig, PREVIEW_STATES, type Plugin, PluginError, type PreviewState, type SetupOptions, type VisionOptions, type VisionPlugin, plugin, vision };