Organizations that want participants to be able to take the online test directly on their website are able to do so by embedding the test within an iframe. Embedding an iframe requires additional setup than adding a link to your online test.
The video below will demonstrate a few examples of what the embedded online test could look like on a webpage:
In this article:
- To enable embedding
- iFrame code snippets
- Passing URL parameters to an iframe
- Integrating an iframe communication layer
To enable embedding
The first step to embedding your online test is to enable embedding in your SHOEBOX web portal. This can only be done by an admin user.
- Log in to the SHOEBOX Data Management Portal.
- In the sidebar, hover over the Settings tab.
-
Under the SHOEBOX Online heading, click Advanced.
- In the top-right corner of the page, click Edit.
- In the Embed Test section, enable the toggle switch.
- In the Web Page URL field, enter the URL of the page that will contain the iframe.
- For Testing Purposes: IP addresses and localhost can be used to test your implementation before publishing to production.
- For Production Implementation: To improve SEO, include the full URL of the page that will contain the iframe.
-
Click Add.
- In the top-right corner of the page, click Save.
With this feature enabled, you can embed the online test on the website page provided.
iFrame code snippets
To enable dynamic resizing for your embedded iframe, you will need to add the following code snippet (which includes a script for a responsive iframe resizer) to the HTML of the web page where the iframe will be embedded. For more information on the iFrame Resizer Library, see the developer's Github entry.
Code Snippet
<script src="https://shoeboxonline.com/contents/iframeResizer.min.js"></script>
...
<iframe id="shoeboxonlineiframe" src="https://shoeboxonline.com/<YOUR_SITE_HERE>?" scrolling="no"></iframe>
...
<script> iFrameResize({}, '#shoeboxonlineiframe') </script>
To add the code snippet to your web page
- Copy the code snippet provided above and paste it into the web page that will be hosting your SHOEBOX Online test.
-
In the snippet, replace the text <YOUR_SITE_HERE> with the URL for your SHOEBOX Online test. You can find this URL on the Test Setup page in your SHOEBOX Data Management Portal.
-
In the web page’s <head> section, add the following <meta> tag specifying the viewport attribute (this will make your parent page mobile friendly):
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> -
Under the <meta> tag, add a <style> tag that specifies the width of the iframe for both mobile and desktop screens. For an example, see image below.
- After completing the above steps, your web page should display a responsive iframe that contains your SHOEBOX Online test.
Passing URL parameters to an iframe
If you are using URL parameters such as refid, refSource, or UTM parameters but want to embed the online test on to your website, you will need to add some code so that the iframe has knowledge of these parameters.
While there are many methods your web developer could use to pass the URL parameters to the iframe, we have provided a code snippet example that uses javascript.
Instructions and code snippets
- Under the <iframe> call, place the snippet provided below.
- Ensure the value of the "id" in the <iframe> call and the "elementId" in the code snippet below are identical.
The code snippet will pass all URL parameters to the iframe. You do not have to explicitly define the URL parameters used.
<script>
// ID of the iframe that embeds SHOEBOX Online const elementId = 'shoeboxonlineiframe'
// Add strings to restrict what query parameters from the parent page will be passed to the iframe.
// Leave empty to allow all query parameters.
const allowedParams = [ ]
const embedSrc = new URL(document.getElementById(elementId).src)
const embedParams =new URLSearchParams(embedSrc.search)
const parentParams = new URLSearchParams(window.location.search)
parentParams.forEach ( (value, key) => { if (!allowedParams.length | | allowedParams.includes(key) ) { embedParams.set (key, value) }} )
embedSrc.search = embedParams.toString( ) document.getElementById(elementId).src = embedSrc.toString( )
</script>Integrating an iframe communication layer
If you use an embedded online test and wish to receive information about participant interactions during the test, you can do so by setting up an iFrame Communication Layer. The information gathered can be used to leverage campaign tracking tools or funnel participants that drop off from specific spots in the test.
To set up the iframe communication layer
To receive data from an embedded iframe, add the following snippet to set up an event listener in your organization’s website.
<script type="text/javascript">
window.addEventListener("message", (event) => {
// Do we trust the sender of this message?
var authorizedOrigins = ['https://shoeboxonline.com', 'https://www.shoeboxonline.com'];
if (authorizedOrigins.indexOf(event.origin) < 0) return;
//Ignore iFrame resizer events
if(event.data?.includes("iFrameSizer")) return;
var sboPayload = JSON.parse(event.data);
//Here you can leverage the payload and send data to your analytics tools!
}, false);
</script>Once this is in place, the event listener will start actively checking for events occurring in the iframe, and will send data to you based on the events that occur when a participant engages in the online test.
Event examples
Page view: Sent when a customer views a specific page.
{'eventType': 'screen-view','eventData':
{'screenName': 'splash-screen'
}}List of tracked screens
| Page/Modal | Screen Name |
|---|---|
| Splash Screen | splash-screen |
| Getting started - How it Works | getting-started |
| Demographics - Before we start | demographics |
| Contact Capture - pre-test | pre-test-contact-capture |
| Questionnaire | questions |
| Setup - headset, volume, audio | setup |
| Pure tone test | estimate-threshold |
| Results | results |
| Privacy Statement Modal | privacy-statement-modal |
| Language Selection Modal | select-language-modal |
| "Can’t hear audio" link in audio setup | cannot-hear-audio-modal |
| "Hear audio in both ears" in audio setup | hear-audio-in-both-ears-modal |
| Help on setting device volume in audio setup | set-device-volume-modal |
| Maximum volume is reached in Pure Tone test | puretone-max-limit-reached-modal |
| "How is my result calculated?" on result page | how-my-result-is-calculated-modal |
Screener completed: Sent when a customer has completed a screener. This will also tell you:
- The resultUUID, which is a unique identifier for the participant's result.
- The participant's selected language.
{'eventType': 'screener-completed','eventData':
{'resultUUID': '5b636abf-0e16-4084-b77a-eae79e589f7d', 'language': 'en'
}}Results uploaded: Sent after the screener has successfully uploaded the results to the server. This will also tell you:
- The resultUUID, which is a unique identifier for the participant's result.
- The participant's selected language.
{eventType: 'results-uploaded',eventData:
{resultUUID: '5b636abf-0e16-4084-b77a-eae79e589f7d',language: 'en'
}}Result call-to-action clicked: Indicates when a customer has clicked the call-to-action button on a result page. This will also tell you:
- The resultUUID, which is a unique identifier for the participant's result.
- The call-to-action button’s URL (CTAURL), which is the URL that your organization's call-to-action button links to.
- The call-to-action button’s text (CTAtext), which is the text displayed on your organization's call-to-action button.
{'eventType': 'result-cta-clicked','eventData':
{'resultUUID': '5b636abf-0e16-4084-b77a-eae79e589f7d',
'CTAURL': 'https://myctalink.com?someParameter=10'
'CTAtext': 'Buy a hearing aid now!'
}}