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
| Event | Payload | Fires 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. |
onLiveCameraClick | none | The customer chooses the live camera. |
onRealTimeClick | none | The customer starts the real-time try-on. |
onTakePhotoClick | none | The customer chooses to take a photo. |
onChooseFileClick | none | The customer chooses to upload a photo. |
onSelectModelClick | none | The customer chooses a model. |
onPhotoUse | none | The customer confirms the photo. |
onPhotoRetake | none | The customer retakes the photo. |
onCameraPermissionDeny | none | The 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. |
onProductSelect | Product | The customer selects a product. |
onVariantSelect | Variant | The customer selects a shade to try on. |
onAddToCart | Variant[] | The customer adds one or more shades to the cart. |
onGoToProduct | Variant | The 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[];
}