Skip to main content

Iframe Compatibility & Handling Navigation

Bambuser One-to-One solution has several features (listed below) that utilize the concept of rendering your website inside an iframe. This is usually compatible with websites that are functional when opened within an iframe. For edge cases when this is not fully supported, Bambuser will potentially be able to provide you with workarounds.

Exceptions for SPA site

If you have a full Single Page Application site, you can skip to Exceptions for SPA section


All above listed features utilize technology of creating an iframe element (according to W3C: The iframe element) over the merchant’s landing page to let your end customers (callers) surf the merchant website (inside the iframe) without any interruption while in a call. We do this to prevent page reloading while navigating around the website, since page reloading would destroy the instance of The Call Widget which would end up in call ending abruply.


  • Your website is allowed to be rendered within an <iframe> while the ancestor of the <iframe> is your website
  • <body> element should not have fixed positioning

Potential obstacles and solutions

Some strict server-side security policies might block requests from within an iframe element. If the merchant web server responses contain headers that deny the right of opening web pages within an iframe, Bambuser can not guarantee the full functionality of your website being rendered in an iframe.

Potential incompatibility reasons:

Cross domain access
  • Obstacle: Page on which caller initiates The Call Widget from is not hosted on the same domain and protocol as merchant website/product pages/checkout pages/etc...

  • Possible solution: The Call Widget will by default recognize the redirection to another domain and trigger a popup on end users screen asking whether they want to leave the call. If they choose to leave the call, the page will reload and call will be abrupted.

    If you would like to keep the call going, you can instead add target="_blank" attribute to your ahref links leading to external domains. You might want to do that just in the context when your website is being rendered inside an iframe. You can recognize this by below script on page load:

    Example code:

  • document.addEventListener("DOMContentLoaded", (event) => {
    //true if your page is being rendered in an iframe
    if (top !== self) {

    // note that this is just an example, you will need to
    // define your own ahrefs buttons specifically for your website
    let externalDomainLink = document.getElementById("externalDomainLinkId");

    //_blank will open the page in new tab
    externalDomainLink.setAttribute("target", "_blank");
X-Frame-Options (RFC7034)
  • Obstacle: Response headers from a merchant web server that contains X-Frame-Options = DENY
  • Possible solution: Set X-Frame-Options = SAMEORIGIN


    The Content-Security-Policy HTTP header has a frame-ancestors directive which obsoletes this header for supporting browsers.

CSP: frame-ancestors directive (content security policy level 2)

The Content-Security-Policy header that has a frame-ancestors directive will obsoletes X-Frame-Options header for supporting browsers.

Exception for SPA (Single Page Application) websites

In case your website is a SPA, where viewers can dynamically navigate to other pages of the website without new page load, there is the possibility to skip the overlay iframe. So, the Bambuser Call Widget feature will be an overlay on the actual landing page with no iframe involved. Note that in that case, none of the above-mentioned requirements are needed to be satisfied.

Note that you will need some development effort to configure navigation for your SPA website. Follow below steps to configure navigation for SPA site:

1. Configure the floating player navigationMode

  • By setting the navigationMode to BambuserOneToOneEmbed.FLOATING_PLAYER_NAVIGATION_MODE.MANUAL, your website will NOT be loaded inside an iframe, once the Call Widget is minimized.
let oneToOneEmbed = new BambuserOneToOneEmbed({
floatingPlayer: {
confirmClosingBrowser: true, // (optional) "default=true "
  • By default, Bambuser Call Widget will force a popup whenever an end user clicks on a link that leads to extral domain. If you have an SPA site, you can optionaly disable those pop-ups by setting confirmClosingBrowser to false. This will allow for full page reload in expense to the call ending abrubtly. Therefore, we would recommend not changing the default setting confirmClosingBrowser: true.

2. Handle goto-checkout event

Whenever you are navigating to a checkout URL from the widget, the widget gets minimized and the app should navigate to the checkout URL. Since navigation/routing might work differently on each SPA app, you will have to handle navigation by yourself (manually).

oneToOneEmbed.on('goto-checkout', () => {

// **Option 1**: Enable miniplayer
// Call will minimize and navigate to end user will be navigated to checkour URL

// **Option 2**: Open checkout page in new tab
// oneToOneEmbed.floatAbove('https://your-checkout-url-here', '_blank');

3. Handle surf-behind-to event

If you run manual navigation mode, your site needs to handle the surf behind events from Bambuser like the following code.

oneToOneEmbed.on('surf-behind-to', (url) => {
// Step 1. Load page content without reloading the page
// eg. Use React Router,AJAX , ...

// Step 2. (If needed) Change url inside browser address bar
// eg. history.pushState({}, 'Your Page Title', url)