Widget reference

embed.js turns a container into the ShowroomPro ring builder. It is a single small script with no dependencies. Your quiz token is the quizToken from the sandbox API, or the token in Settings → Embed in the ShowroomPro dashboard. Replace YOUR_TOKEN below with it. The token is public and safe to put in page code.

#Display modes

#Inline (recommended)

The ring builder renders inside the page. The iframe grows and shrinks with the quiz, so there is no fixed height and no inner scrollbar.

<div data-showroompro-ring-builder="YOUR_TOKEN"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>

#Floating launcher

A "Design your ring" button stays in the corner of every page and opens the ring builder in a popup. Put it in the site-wide footer or layout.

<script src="https://www.showroompro.ai/embed.js" data-token="YOUR_TOKEN" data-mode="floating" async></script>

#Popup button

A button appears where the container sits and opens the ring builder in a popup.

<div data-showroompro-ring-builder="YOUR_TOKEN" data-mode="popup"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>

#Your own button or link

Load the script with your token and no mode, then point any link at #showroompro-ring-builder. Nothing is drawn until the link is clicked.

<script src="https://www.showroompro.ai/embed.js" data-token="YOUR_TOKEN" async></script>

<a href="#showroompro-ring-builder">Design your ring</a>
<a href="#showroompro-wedding-band">Design your wedding band</a>

Any element with data-showroompro-open="YOUR_TOKEN" also opens the popup on click, and data-quiz="wedding-band" on that element opens the wedding band path.

#Wedding bands

Add data-quiz="wedding-band" to the container (or to the script tag for the floating launcher):

<div data-showroompro-ring-builder="YOUR_TOKEN" data-quiz="wedding-band"></div>
<script src="https://www.showroompro.ai/embed.js" async></script>

This starts the quiz with Wedding band selected. It has no effect unless the Wedding Band Builder is turned on for the account.

#Attributes

Set these on the container, or on the script tag for the floating launcher.

Branding inside the quiz (logo, colors, welcome text, which options shoppers can pick, language) is set in the ShowroomPro dashboard, not with attributes.

#Behavior you can rely on

• One script per page. Loading embed.js twice is harmless; the second copy does nothing.
• Late containers mount automatically. The script watches the page, so containers added by React, Vue, Next.js or a page builder after load are mounted without extra code. Call ShowroomPro.mount() to force it.
• Mobile. Inline mode fits the container width. The popup is full screen on phones.
• Install detection. When the widget loads on a real domain, ShowroomPro records the domain and the dashboard shows Live on: yoursite.com. Localhost and raw IP addresses are not recorded. A wrong token logs a warning in the browser console.

#JavaScript API and events

embed.js exposes window.ShowroomPro:

ShowroomPro.open();                          // open the popup
ShowroomPro.open({ quiz: "wedding-band" });  // open the wedding band path
ShowroomPro.close();                         // close the popup (no confirmation)
ShowroomPro.isOpen();                        // true while the popup is open
var stop = ShowroomPro.on("design_generated", function (detail) {
  console.log("design ready", detail.sessionId);
});
stop();                                      // or ShowroomPro.off(name, fn)
ShowroomPro.on("*", function (detail) { console.log(detail.event, detail); });
ShowroomPro.mount();                         // mount containers added after load

The same events are dispatched as DOM events named showroompro:<event>. They fire on the container (or the button that opened the popup) and bubble up to window. Listen for showroompro:ready if you need to know when the API is available:

window.addEventListener("showroompro:ready", function () {
  document.querySelector("#my-button").onclick = function () { ShowroomPro.open(); };
});

Every lifecycle event detail also includes event, mode and quiz. Events never contain the shopper's name, email or phone number. Leads stay in the dashboard, or arrive through webhooks.

Older installs may listen for ringbuilder:quiz_started, ringbuilder:design_generated and ringbuilder:design_approved. These aliases still fire.

#Iframe fallback

Some site builders remove <script> tags. In that case use a plain iframe:

<iframe src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN" width="100%" height="800" frameborder="0" style="border:none;"></iframe>

For wedding bands, add &quiz=wedding-band to the URL. The iframe has a fixed height, does not resize with the quiz, and is not counted for install detection. Use the script snippets whenever the platform allows them.

#Auto-resizing a hand-written iframe

Add sp_autosize=1 to the URL (optionally sp_min_height=700). The quiz then posts its height and you resize the iframe yourself:

<iframe id="sp-quiz" src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN&sp_autosize=1" style="width:100%;border:0;height:600px"></iframe>
<script>
  window.addEventListener("message", function (e) {
    if (e.origin !== "https://www.showroompro.ai") return;
    if (e.data && e.data.type === "showroompro:resize") {
      document.getElementById("sp-quiz").style.height = e.data.height + "px";
    }
  });
</script>

#Existing installs keep working

Nothing on an existing site needs to change. These older forms still work:

• <script src="…/embed.js?token=YOUR_TOKEN"></script> with links to #ringbuilder-quiz, or elements with data-ringbuilder-quiz="YOUR_TOKEN"
• <iframe src="https://www.showroompro.ai/embed/quiz?d=YOUR_TOKEN">
• script tags loaded from ringbuilder.ai or showroompro.ai

Use the snippets above for new installs.

#Content Security Policy

If the site sends a Content-Security-Policy header, allow ShowroomPro:

script-src  https://www.showroompro.ai;
frame-src   https://www.showroompro.ai;
connect-src https://www.showroompro.ai;

Add these to the directives you already have rather than replacing them.

#Troubleshooting

• Nothing appears. Check the browser console for [ShowroomPro] warnings. Make sure the token is right and the script URL is exactly https://www.showroompro.ai/embed.js.
• The builder removed my script. Use the iframe fallback, or the platform's site-wide code injection (see the install guides).
• Dashboard says "not live yet". Load the page on the real domain, not a preview or localhost URL.
• Inline widget is cut off. A parent element has a fixed height or overflow: hidden. Remove it, or use popup mode.