Actions reference
Actions are functions you call on the pulpoar object to control the plugin.
| Action | Summary |
|---|---|
applyVariants | Apply variants by slug, or clear them |
applyVariantsWithCatalog | Apply variants and select them in the catalog |
addVariantsWithCatalog | Add variants to the current selection |
setPath | Navigate to a screen |
setImageToApply | Apply makeup on your own image |
initCamera | Start the camera |
setCameraFeedStatus | Pause or resume the camera |
setShowBackButton | Show or hide the back button |
setShowCloseButton | Show or hide the close button |
updateCatalogWithCustomValues | Set available variants and custom values for this session |
setVariantsStatus | Enable or disable specific variants |
setVariantsVisibility | Show or hide specific variants |
setPartnerAnalyticsId | Link analytics events to your user ID |
applyVariantsWithCatalog, updateCatalogWithCustomValues, setVariantsStatus and setVariantsVisibility only work when the plugin's catalog is initialized.
Applying variants
applyVariants
Applies variants by their slugs. Pass an empty array to remove all applied makeup.
applyVariants(slugs: string[], callback?: (variants: Variant[]) => void): void
pulpoar.applyVariants(['lipstick-red', 'eyeshadow-brown'], (applied) => {
console.log('Applied', applied);
});
// Remove all makeup
pulpoar.applyVariants([]);
applyVariantsWithCatalog
Applies variants and also selects their product, category and brand in the catalog, so the catalog UI shows what's applied. Pass an empty array to reset.
applyVariantsWithCatalog(slugs: string[], callback?: (variants: Variant[]) => void): void
pulpoar.applyVariantsWithCatalog(['lipstick-red']);
addVariantsWithCatalog
Adds variants to the current selection instead of replacing it. Applied variants from the same category as a new variant are replaced. The slugs array must not be empty. Catalog selections (product, category and brand) are updated only when the catalog is initialized.
addVariantsWithCatalog(slugs: string[], callback?: (variants: Variant[]) => void): void
// Lipstick is applied; add an eyeshadow without removing it
pulpoar.addVariantsWithCatalog(['eyeshadow-brown']);
Navigation and camera
setPath
Navigates to a screen.
setPath(path: 'root' | 'choose-model' | 'take-photo' | 'apply-live' | 'apply-photo'): void
| Path | Screen |
|---|---|
root | Start screen |
choose-model | Model selection |
take-photo | Take a photo with the camera |
apply-live | Live camera try-on |
apply-photo | Try-on on a photo |
pulpoar.setPath('apply-live');
setImageToApply
Sets your own image (a URL or a base64 string) as the image to apply makeup on. Use it with setPath('apply-photo'), or in custom mode.
setImageToApply(image: string): void
pulpoar.setImageToApply('https://example.com/model.jpg');
pulpoar.setPath('apply-photo');
initCamera
Starts the camera with the given facing mode.
initCamera(constraints: { facingMode: 'user' | 'environment' }): void
pulpoar.initCamera({ facingMode: 'user' });
setCameraFeedStatus
Pauses or resumes a camera that's already running, without destroying it. For example, pause it while your own modal covers the try-on.
setCameraFeedStatus(status: 'enabled' | 'disabled'): void
pulpoar.setCameraFeedStatus('disabled'); // pause
pulpoar.setCameraFeedStatus('enabled'); // resume
UI controls
setShowBackButton
setShowBackButton(show: boolean): void
setShowCloseButton
setShowCloseButton(show: boolean): void
Per-user catalog
These actions change catalog data for the current session only. Your global catalog isn't affected. See Per-user catalog customization for full examples.
All three take a list of variants identified by slug:
type CustomVariant = {
slug: string;
price?: string;
name?: string;
image?: string;
thumbnail_color?: string;
web_link?: string;
};
updateCatalogWithCustomValues
Sets which variants are available and overrides their values. Only the variants you pass stay available. All others are marked out of stock with outOfStockText.
updateCatalogWithCustomValues(options: {
variants: CustomVariant[];
outOfStockText?: string;
}): void
pulpoar.updateCatalogWithCustomValues({
variants: [
{ slug: 'lipstick-red', price: '€19.90' },
{ slug: 'lipstick-pink', price: '€17.90', web_link: 'https://shop.example.com/pink' },
],
outOfStockText: 'Not available in this store',
});
setVariantsStatus
Enables or disables only the variants you pass. Other variants don't change. When isDisabled is true (the default), the variants are shown as out of stock.
setVariantsStatus(options: {
variants: CustomVariant[];
isDisabled?: boolean; // default: true
outOfStockText?: string;
}): void
pulpoar.setVariantsStatus({
variants: [{ slug: 'lipstick-red' }],
isDisabled: true,
outOfStockText: 'Sold out',
});
setVariantsVisibility
Shows or hides variants. Hidden variants are removed from the UI completely.
mode: 'merge'(default): only the variants you pass change.mode: 'replace': all variants become visible first, then the ones you pass are hidden.
setVariantsVisibility(
options: {
variants: Array<{ slug: string; hidden: boolean }>;
mode?: 'merge' | 'replace';
},
callback?: (result: { notFound: string[] }) => void
): void
pulpoar.setVariantsVisibility(
{ variants: [{ slug: 'discontinued-shade', hidden: true }] },
({ notFound }) => console.log('Unknown slugs:', notFound)
);
// Show all variants again
pulpoar.setVariantsVisibility({ variants: [], mode: 'replace' });
Analytics
setPartnerAnalyticsId
Links analytics events to your own user or account ID, for example after login. The ID can contain letters, digits, ., _ and -, up to 128 characters.
setPartnerAnalyticsId(
id: string | number | null,
callback?: (result: { partnerAnalyticsId: string | null }) => void
): void
pulpoar.setPartnerAnalyticsId('user-123');
// On logout
pulpoar.setPartnerAnalyticsId(null);
- The ID applies only to events after the call. If you know the ID before the plugin loads, add
#partnerAnalyticsId=<id>to the iframe URL instead, so startup events are linked too. - Passing
nullclears the ID. An invalid ID also clears it and triggersonError.