Web Integration
Embed the plugin in an iframe, and load the JavaScript SDK on the same page if you want to listen to events.
There are two layouts:
- Embedded: the plugin is part of the page.
- Responsive modal: a button opens the plugin in a modal on desktop and full screen on tablet and mobile.
Embedded
<iframe
id="hto-iframe"
src="https://plugin.pulpoar.com/hto/<project-key>"
allow="camera *;"
title="Hair Color Try-On"
style="border: none; width: 1200px; height: 720px;"
></iframe>
<style>
@media (max-width: 768px) {
#hto-iframe { width: 100% !important; height: 768px !important; }
}
</style>
<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
pulpoar.onReady((payload) => console.log('Ready:', payload));
pulpoar.onAddToCart((variants) => console.log('Add to cart:', variants));
</script>
The allow="camera *;" attribute is required for the camera to work inside the iframe.
Responsive modal
<button id="open-hto">Try hair colors</button>
<div class="modal-overlay" id="hto-modal">
<div class="modal-content">
<button class="close-button" id="close-hto" aria-label="Close">✕</button>
<iframe id="hto-iframe" allow="camera *;" title="Hair Color Try-On"></iframe>
</div>
</div>
<style>
.modal-overlay {
position: fixed; inset: 0; z-index: 1000;
display: none; align-items: center; justify-content: center;
background: rgba(0, 0, 0, 0.5);
}
.modal-overlay.open { display: flex; }
.modal-content {
position: relative; width: 1160px; height: 700px;
background: #fff; border-radius: 12px; overflow: hidden;
}
.close-button { position: absolute; top: 8px; right: 12px; z-index: 10; }
#hto-iframe { width: 100%; height: 100%; border: none; display: block; }
/* Tablet and mobile: full screen */
@media (max-width: 1200px) {
.modal-content { width: 100%; height: 100dvh; border-radius: 0; }
}
</style>
<script>
const modal = document.getElementById('hto-modal');
const iframe = document.getElementById('hto-iframe');
document.getElementById('open-hto').addEventListener('click', () => {
iframe.src = 'https://plugin.pulpoar.com/hto/<project-key>';
modal.classList.add('open');
document.body.style.overflow = 'hidden'; // lock page scroll
});
document.getElementById('close-hto').addEventListener('click', () => {
modal.classList.remove('open');
document.body.style.overflow = '';
iframe.src = 'about:blank'; // releases the camera
});
</script>
Iframe dimensions
The iframe size decides which layout the plugin shows. Use these sizes:
| Layout | Device | Width | Height |
|---|---|---|---|
| Embedded | Desktop | 1200px | 720px |
| Embedded | Mobile | 100% | 768px |
| Modal | Desktop | 1160px | 700px |
| Modal | Tablet and mobile | 100% | 100dvh (full screen) |
The plugin switches layout at these widths:
| Layout | Iframe width |
|---|---|
| Desktop | 1135px and above |
| Tablet | 701px to 1134px |
| Mobile | 700px and below |
Avoid widths close to a breakpoint. The plugin may switch to a smaller layout unexpectedly. Always test with the sizes above.
Open a specific item
Add a brand, category, product or variant to the URL to open the plugin with it selected:
https://plugin.pulpoar.com/hto/<project-key>/brand/<slug>
https://plugin.pulpoar.com/hto/<project-key>/category/<slug>
https://plugin.pulpoar.com/hto/<project-key>/product/<slug>
https://plugin.pulpoar.com/hto/<project-key>/variant/<slug>
You can use the item's slug or UUID. These are the same links Studio creates in Direct Links.
Language
Add lang to set the language of the plugin's built-in text: en, tr, pt, it, fr or ru.
https://plugin.pulpoar.com/hto/<project-key>?lang=fr
If lang isn't set, the plugin uses the browser language, and falls back to English. You can change the text for each language in Studio with the Theme Designer.