Skip to main content

Expivi SDK

This guide explains how to use Expivi SDK as a package in your own application. It starts with the overall lifecycle of a configurator session and then documents the public use* hooks exposed by @expivi/product-configurator.

At a high level, an Expivi integration is built around three layers:

  1. ProductConfigurator holds product state, loads product data, runs rules, and serializes configuration.
  2. Your application mounts its UI and provides access to the configurator instance.
  3. use* hooks expose read and write controllers for products, attributes, layout entities, messages, pricing, media, quote requests, and Web2Print flows.

Minimal flow​

import { ProductConfigurator } from "@expivi/product-configurator";

const configurator = new ProductConfigurator({
  apiBaseUrl: "...",
  apiToken: "...",
});

await configurator.loadProduct(productId);

After loading, you can create controllers such as:

const global = useProductConfigurator(configurator);
const products = useStoreProductOffers(configurator);
const messages = useMessages(configurator);

Typical host application flow​

Most applications follow this sequence:

  1. Initialize ProductConfigurator with API credentials and optional locale settings.
  2. Call loadProduct(productId).
  3. Wait until the configurator is in a usable lifecycle state.
  4. Create hook controllers for the parts of the SDK your UI needs.
  5. Render product UI, messages, media pickers, quote forms, or Web2Print tooling on top of those controllers.

Initialization model​

Most hook controllers require the configurator to already be initialized. In practice, create useProductConfigurator(configurator) first, watch its status, and create the rest of your controllers once the configurator reaches LOADED or READY.

Guide structure​

  • getting-started/bootstrapping explains package setup and the configurator lifecycle.
  • getting-started/app-shell explains how to structure your host UI around controller state.
  • hooks/* documents every public hook exported as use* from @expivi/product-configurator.