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
| Action | Parameters | Description |
|---|---|---|
setPartnerAnalyticsId | id: string | number | null, callback?: (result: { partnerAnalyticsId: string | null }) => void | Links 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
| Event | Payload | Fires when |
|---|---|---|
onReady | { projectKey: string; themeType: string } | The plugin is ready. |
onError | string | An 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. |
onPhotoUse | none | The customer confirms the photo. |
onPhotoRetake | none | The customer retakes the photo. |
onCameraPermissionDeny | none | The 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;
}