Integration patterns
There are three common ways to place VTO on a website:
| Pattern | Use it for | Iframe size |
|---|---|---|
| Responsive modal (recommended) | A "Try it on" button anywhere on your site | Desktop 1160 × 700 px, tablet/mobile full screen |
| Landing page | A dedicated VTO page or section showing your whole catalog | Desktop 1200 × 720 px, mobile 100% × 768 px |
| Product detail page (PDP) | Trying on a single product from its product page | Same as modal or landing page |
Responsive modal (recommended)
The modal pattern is recommended for most launches. It keeps your page intact and gives the plugin a focused surface:
- Desktop (> 1200 px): a centered modal of 1160 × 700 px, with the close button over the iframe to save vertical space.
- Tablet and mobile: full screen (100% × 100dvh) with a slim header for the close button, and page scroll locked.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>VTO - Responsive Modal Integration</title>
<style>
.modal-overlay {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.5);
display: flex;
align-items: center;
justify-content: center;
opacity: 0;
pointer-events: none;
transition: opacity 0.3s;
z-index: 1000;
}
.modal-overlay.open { opacity: 1; pointer-events: auto; }
.modal-content {
position: relative;
width: 1160px;
height: 700px;
background: white;
border-radius: 12px;
overflow: hidden;
display: flex;
flex-direction: column;
}
.desktop-close-button {
position: absolute;
top: 8px;
right: 12px;
z-index: 10;
}
.mobile-header { display: none; justify-content: flex-end; height: 28px; padding: 0 8px; }
#vto-iframe { border: none; width: 100%; height: 100%; display: block; }
@media (max-width: 1200px) {
.modal-content { width: 100%; height: 100dvh; border-radius: 0; }
.desktop-close-button { display: none; }
.mobile-header { display: flex; }
#vto-iframe { height: calc(100dvh - 28px); }
}
</style>
</head>
<body>
<button onclick="openVTO()">Try it on</button>
<div id="modal" class="modal-overlay">
<div class="modal-content">
<button class="desktop-close-button" onclick="closeVTO()" aria-label="Close">✕</button>
<div class="mobile-header">
<button onclick="closeVTO()" aria-label="Close">✕</button>
</div>
<iframe id="vto-iframe" allow="camera *;"></iframe>
</div>
</div>
<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
const modal = document.getElementById('modal');
const iframe = document.getElementById('vto-iframe');
function openVTO() {
iframe.src = 'https://plugin.pulpoar.com/vto/<project-key>';
modal.classList.add('open');
document.body.style.overflow = 'hidden';
}
function closeVTO() {
modal.classList.remove('open');
document.body.style.overflow = '';
}
modal.addEventListener('click', (e) => {
if (e.target === modal) closeVTO();
});
pulpoar.onReady((payload) => console.log('VTO ready:', payload));
pulpoar.onAddToCart((variants) => console.log('Added to cart:', variants));
</script>
</body>
</html>
Set the iframe src only when the modal opens. The plugin then loads, and asks for the camera, only when the user actually wants to try on.
Landing page
Use the embedded pattern when VTO is the main content of a page or section. The plugin loads your whole project and shows the full catalog: brands, categories, products and looks.
<style>
iframe {
border: none;
width: 1200px;
height: 720px;
}
@media (max-width: 768px) {
iframe {
width: 100%;
height: 768px;
}
}
</style>
<iframe src="https://plugin.pulpoar.com/vto/<project-key>" allow="camera *;"></iframe>
<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
pulpoar.onAddToCart((variants) => {
console.log(variants);
});
</script>
Product detail page (PDP)
Use the PDP pattern when the plugin should serve one product only. The plugin fetches just that product, so users can try its shades right away.
Make sure the product has a slug assigned in PulpoAR Studio or through the Partner API.
<iframe
src="https://plugin.pulpoar.com/vto/<project-key>/product/<product-slug>"
allow="camera *;"
></iframe>
Applying variants from your own product page
If your product page already has its own shade picker, you can hide the plugin's catalog with ?catalog=false and apply shades from your page through the SDK:
<iframe
src="https://plugin.pulpoar.com/vto/<project-key>?catalog=false"
allow="camera *;"
></iframe>
<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
// Apply the shade that is selected on your product page
pulpoar.applyVariants(['<variant-slug>']);
// When the user picks another shade on your page
function onShadeClick(slug) {
pulpoar.applyVariants([slug]);
}
</script>
For a fully custom UI, see Custom UI.