Skip to content
Gallery
TestBox Partner Documentation
Getting Started
iFraming
Auto-login
More
Share
Explore

icon picker
iFraming

Update HTTP Headers

First, we need to prepare your web application to serve the correct HTTP headers to allow iFraming inside TestBox.

Removing X-Frame-Options
​
⁠
⁠

Many web applications today include an X-Frame-Options header on all responses with a value of DENY. This prevents your web app from being framed anywhere. This is generally a safe option, but unfortunately is incompatible with integrating with TestBox.
The first step is to remove your usage of this header. We will instead use the more advanced Content-Security-Policy header to control the framing of your web app. Plus, doing so will move your web app in to the future, as
X-Frame-Options is considered obsolete!
⁠
⁠

Adding or changing Content-Security-Policy
​
⁠
⁠

If you do not currently use Content-Security-Policy, you should prepare your web framework to add this header to all HTTP responses. The minimal Content-Security-Policy value that works with TestBox would look like this in an HTTP response:
If you currently serve a Content-Security-Policy header, you may want to add our domain to any pre-existing frame-ancestors:

Additional advantages to Content-Security-Policy
​
⁠
⁠

Content-Security-Policy is a powerful browser feature to protect the security and integrity of your web app. It allows you to control, very specifically, what content is allowed to load and execute on your site. If you are introducing Content-Security-Policy to your web app for the first time, we definitely suggest you have a look at some of the other directives available to you.

Dynamically allowing framing
​
⁠
⁠

If you are not comfortable with removing the X-Frame-Options header entirely, you may want to consider dynamically removing the header based on whether or not an account is a TestBox account. However, this would require usage of JWT-based SSO, something that is discussed in
auto-login
⁠
. Please contact us for guidance if this is an option you'd like to explore.

Install TestBox JavaScript

Because your web app and TestBox operate on different domains, it is impossible for our front-end to make inquiries about the status of the iFrame directly. As such, we have built messaging infrastructure to communicate the health and status of the iFrame. This requires a small amount of JavaScript to be added to your HTML head, as shown here:

Installation
​
⁠
⁠

First, install
the package
⁠
in to your front-end.
npm i @testboxlab/browser
yarn add @testboxlab/browser

Usage and Purpose
​
⁠
⁠

This package provides two sets of functionality:
Communication to TestBox for user experience purposes
⁠
Client-side Auto-login
⁠
(only if you pursue this option for auto-login; view
Auto-login
⁠
for more details)

Base Usage
​
⁠
⁠

If you just need the basics of TestBox for your app, you'll use something like this:
This will allow TestBox to communicate with your website. This communication is important to remove loading states and generally provide a good user experience.
If you use React, your implementation might look like this:

Navigation
​
⁠
⁠

If you use react-router, or any kind of client-side routing, you may want to override our standard navigation behavior. Navigation happens when a user chooses a use case they want to try out. By default, TestBox will use window.location to push the iFrame to a new URL. You might want to do something more sophisticated.
There are two ways to interact with the browser SDK for events:

Client-side Auto-login
​
⁠
⁠

If you have opted to use our client-side auto-login functionality, you have a bit more work to do. Please view
Auto-login
⁠
for more details.
On your login page/component, you will want to add some code similar to the following:
Like navigation, you can also configure this at run time:

Testing
​
⁠
⁠

Work in progress! For now, we will test this for you. But soon you will have a place to manage and validate this info.
Please reach out to us via your dedicated Slack channel when you’re ready to test the installation and one of our technical leads will assist you with testing.

Cross-domain JavaScript Considerations

Because your web app and TestBox operate on different domains, there are some features in JavaScript that simply do not work.

window.top
​
⁠
⁠

The most notable of which is window.top. If you also use iFrames in your product, it is possible that you use window.top to reach the top-most window for information.
window.top is useful for developers since they do not know how many levels deep their iFrame will be. Unfortunately, being inside of TestBox changes this paradigm quite a lot. window.top will now attempt to access app.testbox.com instad of your own domain, which will result in a "cross-origin error." It also means you probably won't have access to the information or functions you are looking for.
We have a two relatively simple solutions for this problem.

Helper function
​
⁠
⁠

You can use the following helper function:
Instead of calling window.top, use windowTop().

window.safeTop
​
⁠
⁠

You could also do something like this:
This provides an API similar to window.top, allowing for a simple find/replace with window.safeTop.

Other UX Considerations

There are other UX considerations that we should review together to ensure your prospects do not experience unexpected issues when testing inside TestBox.
Frame breaking
​
⁠
: If your app uses a frame-buster, the user could be directed to an experience outside of TestBox. There are TestBox-safe ways to continue frame breaking, please contact us for details.
Usage of target=_blank in links
​
⁠
: Unless you are linking to a truly external party, we recommend leaving the target of links blank wherever possible.


Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.