Skip to main content

JavaScript SDK

The @pulpoar/plugin-sdk package lets your page listen to events from the Hair Color Try-On plugin running in an iframe. It's the same package used for Makeup Virtual Try-On.

Hair Color Try-On has events only. SDK actions, such as applyVariants, are available for Makeup Virtual Try-On only.

Installation​

Load it from a CDN:

<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
pulpoar.onReady(() => console.log('Hair Color Try-On ready'));
pulpoar.onVariantSelect((variant) => console.log('Shade selected:', variant.name));
pulpoar.onAddToCart((variants) => console.log('Add to cart:', variants));
</script>

Or install it from npm:

npm install @pulpoar/plugin-sdk

You can register event listeners any time after the SDK loads. They start receiving events once the iframe loads.

Events​

EventPayloadFires when
onReady{ projectKey: string; themeType: string; entryType: "embedded" | "direct_link"; collectionKey?: string; collectionItemKey?: string }The plugin is ready. entryType is direct_link when the URL opens a specific item.
onPathChange{ referer: string; path: string }The customer moves to another screen.
onLiveCameraClicknoneThe customer chooses the live camera.
onRealTimeClicknoneThe customer starts the real-time try-on.
onTakePhotoClicknoneThe customer chooses to take a photo.
onChooseFileClicknoneThe customer chooses to upload a photo.
onSelectModelClicknoneThe customer chooses a model.
onPhotoUsenoneThe customer confirms the photo.
onPhotoRetakenoneThe customer retakes the photo.
onCameraPermissionDenynoneThe customer denies camera permission.
onGdprApprove{ approved: boolean; secondary?: boolean }The customer responds to the consent prompt.
onGdprLinkClick{ url: string; text: string }The customer clicks a link in the consent prompt.
onBrandSelect{ brandId: string }The customer selects a brand.
onCategorySelect{ categoryId: string }The customer selects a color family.
onProductSelectProductThe customer selects a product.
onVariantSelectVariantThe customer selects a shade to try on.
onAddToCartVariant[]The customer adds one or more shades to the cart.
onGoToProductVariantThe customer clicks Go to Product.

Example: connect to your store​

pulpoar.onAddToCart((variants) => {
variants.forEach((variant) => {
fetch('/api/cart/add', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ sku: variant.custom_slug, quantity: 1 }),
});
});
});

pulpoar.onGoToProduct((variant) => {
window.location.href = variant.web_link;
});

Types​

Variant​

A shade, with the fields set in Studio. The main fields:

{
id: string;
name: string;
slug: string;
custom_slug: string; // your own ID, for example your SKU
barcode: string;
web_link: string; // the product page URL
stock_status: string;
thumbnail_color: string;
product: Product;
}

Product​

{
id: string;
name: string;
slug: string;
custom_slug: string;
brand: { id: string; name: string };
category: { id: string; name: string };
variants: Variant[];
}