Can FullStory capture content that is presented in iframes?

Yes, FullStory can work seamlessly with iframes!

Usually, iframes should just work. However, if you're finding that iframed content is not represented in your playbacks correctly you may need to make a few minor tweaks.

One caveat: If you have content in an iframe for which you do not have access to the code, you will not be able to record the contents of that iframe. One example of this may be a support widget within your application.

This article will cover common implementation scenarios as well as several things to keep in mind when working with iframes.

iframe Implementation Scenarios

Here are some scenarios where iframe recording should work. In the following scenarios, "outer page" refers to the top-most html page, the one not running in an iframe, or

1) The outer page is running FullStory and all your iframes run on the same domain.

For example, you run a single-domain site, and use iframes to organize various components.

What to do: You don't need to do anything special. Run FullStory on the outer page, and everything should get recorded.  If you also have the FullStory recording snippet inside your iframes, that's ok too; the recording script within the iframes will automatically defer to the outer page.

Note: If the same-origin (same domain) iframe is empty when fs.js is executed on the main page, FullStory will not insert itself into that frame and it will not be recorded..

2) The outer page is running FullStory and you have iframes running on a different domain.


Before configuring window['_fs_run_in_iframe'], you should understand the security implications and configure your Content Security Policy (CSP) HTTP headers accordingly- specifically the frame-ancestors directive.

Failure to configure your CSP headers while using this setting can bypass iframe security protections that are included in modern browsers. If you're unsure what this means, please Contact Us for further information before proceeding.

This case applies when you have a mixed-domain site that uses iframes, but logically it's all part of a single application and you want everything recorded together.  (Note: Click here for a detailed explanation of what "cross-origin" means. For example, an iframe from that appears on would be considered a mixed-domain site environment.)

What to do: Put the FullStory recording snippet on the outer page.  Then inside of the iframe, include the FullStory recording snippet again and add this special flag to the script:

window['_fs_run_in_iframe'] = true; // Whoa there! Proceed with caution. Before adding this new variable inside the iframe, beware of the security implications and be sure to configure your CSP headers accordingly. See the security note above for more information.

So the resulting iframe script will look something like:

window['_fs_run_in_iframe'] = true;
window['_fs_debug'] = false;
window['_fs_host'] = '';

The _fs_run_in_iframe flag tells FullStory that the iframe should record itself and communicate with the outer page that is also running FullStory, so they show up together in a single recording.  Again, this is only necessary if the iframe is cross-origin with respect to the outer page.

Note: If you'd like to record an iframe where the sandbox property is set, you'll also have to add  allow-same-origin to the sandbox  property or FullStory will not be able to record the contents of the iframe.


3) The outer page does not run FullStory and you want to record a page that runs in an iframe.

For example, you provide content in an iframe, which is embedded into a third-party site that doesn't use FullStory.

What to do: Inside of the iframe, include the usual FullStory recording snippet and add this special flag to the script:

window['_fs_is_outer_script'] = true;

So the resulting iframe script will look something like:

window['_fs_is_outer_script'] = true;   //  <-- here is the new variable to add, only inside the iframe
window['_fs_debug'] = false;
window['_fs_host'] = '';

The _fs_is_outer_script flag tells FullStory that the iframe is the "root" of the recording, and should be its own session.


4) You want to record a page that runs in an iframe into your FullStory account, but the outer page is recording into a different FullStory account.

For example, maybe you provide content in an iframe, and it's embedded into a third-party site which also happens to be using FullStory, but they have their own FullStory account that's different from yours.

What to do: Follow the instructions from part 3, using the _fs_is_outer_script flag inside the iframe.  The outer page will record itself into one FullStory account, which will render the iframe as an empty box.  The iframe will record itself into a different FullStory account, and all you'll see is the iframe itself, not the content around it.  There is no way to see all the content together in this scenario.

Working with iframes and FullStory

There are a few ways that FullStory behaves differently or perhaps unexpectedly when working with iframes.

Limited support for the FullStory JavaScript API within iframes

The only FullStory JavaScript API method that is supported within iframes is the FS.event API. Calls to other JS API methods within iframes, such as FS.setUserVars or FS.identify, will fail silently.

Using Embedded iframes

If you're using FullStory to record pages with embedded iframes and are also using postMessage() to communicate across frames, you may see some unexpected messages in your message event handler.

FullStory must use the postMessageAPI to communicate recording data from frames up to the parent window, because these frames may be on different domains.
Unfortunately, this communication mechanism has a design flaw in that there's no formal way to designate scripts. Thus, multiple scripts communicating over this channel will receive each others' messages and must find a way to exclude those not intended for it.

If another script on the page doesn't explicitly test the messages it receives, it may show exceptions or other errors. The following is an example of such a case:

window.addEventListener('message', function(e) {
  var msg = JSON.parse(;
}, false);

The above code will throw an exception when it attempts to access msg.someField

The exception is harmless but produces error messages on the Javascript console. The best approach is to guard against this case with a simple test, such as:

window.addEventListener('message', function(e) {
  var msg;

  // Also ensure JSON parsing doesn't fail, because could be text.
  try { msg = JSON.parse(; } catch (e) { }

  // Ensure that this message was actually intended for us.
  if ('someField' in msg) {
}, false);

Approaching message handlers in this way will ensure that they're resilient not just to unexpected messages from fs.js but any other scripts that use postMessage() to communicate across frames.

Need to get in touch with us?

The FullStory Team awaits your every question.

Contact us