Skip to main content

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:

LayoutDeviceWidthHeight
EmbeddedDesktop1200px720px
EmbeddedMobile100%768px
ModalDesktop1160px700px
ModalTablet and mobile100%100dvh (full screen)

The plugin switches layout at these widths:

LayoutIframe width
Desktop1135px and above
Tablet701px to 1134px
Mobile700px and below
warning

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.