Skip to main content

JavaScript SDK

The @pulpoar/plugin-sdk package connects your page to the Skin Analysis plugin running in an iframe. It's the same package used for Makeup Virtual Try-On.

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('Skin Analysis ready'));
pulpoar.onSkinScoreCalculate((payload) => console.log('Skin score:', payload));
pulpoar.onAddToCart((payload) => console.log('Add to cart:', payload));
</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.

Actions​

ActionParametersDescription
setPartnerAnalyticsIdid: string | number | null, callback?: (result: { partnerAnalyticsId: string | null }) => voidLinks analytics events to your own user or account ID, for example after login. Applies to events after the call. Pass null to clear it, for example on logout. An invalid ID also clears it and fires onError.
pulpoar.setPartnerAnalyticsId('user-123', ({ partnerAnalyticsId }) => {
console.log('Partner analytics ID:', partnerAnalyticsId);
});

If you know the ID before the plugin loads, use the #partnerAnalyticsId URL hash instead, so the first events are linked too.

Events​

EventPayloadFires when
onReady{ projectKey: string; themeType: string }The plugin is ready.
onErrorstringAn action fails, for example an invalid partner analytics ID.
onPathChange{ referer: string; path: string }The customer moves to another screen.
onOnboardingCarouselChange{ fromStep: number; toStep: number }The onboarding carousel changes step.
onQuestionAnswer{ question: Question; answers: Answer[] }The customer answers a question.
onQuestionnaireComplete{ questionsAndAnswers: Array<{ question: Question; answers: Answer[] }> }The customer completes the questionnaire.
onPhotoUsenoneThe customer confirms the photo.
onPhotoRetakenoneThe customer retakes the photo.
onCameraPermissionDenynoneThe customer denies camera permission.
onSkinScoreCalculate{ analysisId: string; skinHealthScore: number; isSelfie: boolean; issues: SkinIssue[] }The skin analysis is complete.
onExperienceChange{ experience: "skin-analysis" | "ai-simulation" }The customer switches between the skin report and the AI Simulator.
onRecommendationsReceive{ products: Product[]; routines: Routine[]; isSelfie: boolean }Recommended products and routines are ready.
onProblemChipClick{ problem: string; isSelfie: boolean }The customer clicks a skin concern chip.
onProductTryClick{ product: Product }The customer clicks Try on a product in the AI Simulator, or a product is selected by default.
onAISimulatorAdjust{ product: Product; problem: string; level: number }The customer changes the level in the AI Simulator.
onAddToCart{ products: Product[]; source: "routines" | "products"; experience: "skin-analysis" | "ai-simulation"; routine?: Routine }The customer adds products to the cart. routine is set when they're added from a routine.
onProductVisit{ product: Product; isSelfie: boolean; source: "routines" | "products"; experience: "skin-analysis" | "ai-simulation"; routine?: Routine }The customer clicks a product link. routine is set when the product is opened from a routine.
onEmailButtonClick{ isSelfie: boolean }The customer clicks the email button.
onEmailSend{ isSelfie: boolean; email: string }The results email is sent. email is the address the customer entered.
onExternalProductView{ questionsAndAnswers: Array<{ question: Question; answers: Answer[] }>; skinAnalysisResult: { skinHealthScore: number; issues: SkinIssue[] }; isSelfie: boolean }The customer clicks See Products on the result page. Only fires when External Product View is turned on in the theme settings. Use it to show the recommendations in your own UI.

isSelfie is true when the analysis used a photo of the customer.

Example: connect to your store​

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

pulpoar.onProductVisit(({ product }) => {
window.location.href = `/products/${product.customSlug}`;
});

Types​

Product​

The product fields set in Studio, without nested routines. The main fields:

{
id: string;
name: string | null;
brand: string;
category: string;
customSlug: string; // your own ID, for example your SKU
price: number;
problems: Array<{ issue: string; name: string }>;
aiSimulator?: Array<{
name: string;
levels: Array<{ name: string; image: string }>;
}>;
}

Routine​

{
id: string;
name: string | null;
slug: string | null;
stepName: string | null;
sort: number | null;
}

SkinIssue​

{
id: string;
name: string;
score: number; // usually 0 to 100
}

Question and Answer​

// Question
{
id: string;
header: string;
description: string;
answers: Answer[];
selectionType: "single" | "multiple";
hasAnswerImage: boolean;
hasAnswerDescription: boolean;
image?: string;
}

// Answer
{
id: string;
header?: string;
description?: string;
image?: string;
}