Using Appcues with iFrames
Table of Contents
When working with iFrames you can publish content directly within an iFrame that you control and you can also build flows that span across an outer page and an iFrame that you control.
What Are iFrames?
iFrames, also known as Inline Frames, are essentially a web page within a web page. They're used to display other web pages on your web page whether it's for forms, media, or other material.
Building and publishing within an iFrame
To follow this guide, it is best to already have:
- Installed the “iframe in new tab” Chrome extension
Requirements
- Access to the iFrame original source code.
Installation
Appcues will need to be installed into any iFrame source code that you are using in order to build within the iFrame as well as publish flows to the iFrame. The installation will be just like installing Appcues to your own web app that you have done before. Check out our installation overview here!
Building within an iFrame
With this method you to separate your flow between the steps you will need Outside of the iFrame and Within the iFrame. To build a flow where the flow is triggered by the outer page context (page, event, or manual trigger) and shows some or all of the content inside of an iFrame see Building and Publishing across an iFrame.
Important: take the time to physically draw out your experience where you encounter your iFrame. That way you can visualize what is Outside vs Within the iFrame.
Once Appcues is installed in your iFrame, you can use a Chrome Extension to open the iFrame in a new tab so you can interact with it and build flows! Download here: https://chrome.google.com/webstore/detail/iframe-in-new-tab/lkegfiagmgdnamcfdokgeobfcffnjaci/related?hl=en-US
From here, you can build a flow as normal as if you were building a flow in your web application.
NOTE: If you have a flow in an iFrame and a flow outside of an iFrame on the same page, Appcues will show both flows, due to the nature of iFrames, therefore, we recommend if you have a flow within an iFrame, to only have the flow within the iFrame
Quick iFrame Example
Below this line is a quick example of an iframe of our Docs site displaying a PIN in the iFrame
Step 1: Isolate the iFrame
This is where using the “iframe in new tab” chrome extension comes into play. You can use the Chrome Extension to open the iFrame in a new tab so you can interact with it and build any Appcues experience you desire. From this moment on you would build as you would on your web app.
If you were to right-click on the iFrame with the extension installed, you can see an option to open the iFrame in a new tab/window.
From this moment on, you build as you would on your web app. You can simply open the Appcues extension and build within the iFrame as you normally would another Appcues experience.
Step 2: Target the iFrame domain/URL
As mentioned prior, think of iFrames as a website living within another website. Each one has their own respective domain. When you use the Chrome Extension, you’ll be able to see the domain in the URL. Make sure you add the iFrame domain as available in the Account Settings to be able to choose the domain in the targeting of the Appcues experience you’re looking to publish.
Building and publishing across an iFrame
Note: this functionality requires SDK version 6.1.x or greater, if you are using a fixed SDK version it must be updated to that version or newer for this functionality.
Building and publishing across iFrames allows you to create a flow that is triggered outside of the iFrame and has steps that are target elements inside of, and outside of, the iFrame.
Requirements and limitations
- Hard backdrops are not currently supported for steps that are targeting elements across iFrames.
- iFrame scrolling is not supported on Internet Explorer. We recommend excluding those users from flows that target iFramed content where targeted elements would need to scroll to become visible.
- For security reasons, the iFrames on your page must have the same origin as your host page to use across iFrame element targeting. For the same-origin policy, browsers block scripts trying to access a frame with a different origin. In cases where the host and iframe page are not the same origin, standard browser policy prevents the Appcues builder from targeting elements inside an iFrame and our SDK from accessing these elements and adding event listeners.
Installation
Follow the normal installation process for installing Appcues into the outer portion of your application. Appcues does not need to be, but can be, installed inside of the iFrame.
Building across an iframe
When building a flow that has steps that target iFramed content, add the steps as you normally would. When you have a step that target an element that is inside of the iFrame, use the target selector and select the element that you want to target.
In step settings, selecting Placement > Manual will show you the selector that has been detected.
If any updates are made to the selector it is recommended to only update selector items after the [iframe]
context.
Targeting
When targeting the experience the context of the outer application should be used. For situations where the iFrame context is needed for targeting the Building Within an iFrame approach should be used.
FAQs
1. Which URL conditions should I use in 'Page Targeting'?
As you're building content on a different URL than the parent URL, you should be using conditions that match the iFrame's URL. This will make it so that in the instance of a user reaching a page where there's technically two URLs (parent URL as well as the iFrame's URL), Appcues will attempt to trigger it based on the elements it has found on the Build URL where the iFrame is, instead of the parent URL.
See Page Targeting for more information.
2. Can I create a flow that has steps in an iFrame and outside the iFrame?
While the steps won't technically be inside the iFrame building across an iFrame will allow you to have steps that are outside of an iFrame as well as tooltip steps that target elements inside of an iFrame.
If you decide to build directly within an iFrame the steps of the flow would be within the iFrame.
3. Can experiences built within an iFrame and across an iFrame be shown at the same time?
Yes. Each location that Appcues is installed will operate independently. This means that the outer application would be handled as one location and the iFramed content would be another. While a flow in the outer application can have a tooltip that targets an element inside of the iframe that will not impact the visibility of experiences that are set to show inside the iframe.
4. Can backdrops be used with across iFrame steps?
Soft backdrops will display normally in most applications and hard backdrops are not supported.
5. Can you target across multiple levels of iFrames?
No. When building flows across iFrames, you can target a single level of iFrames. This means that you can build a flow in your application and that flow can target elements in the application or elements that are iFramed into that application. If there is an iFrame within the iFrame those elements will not work across iFrame steps.
6. Can you target iFramed content from another source?
No. Unless the content is set up in a way that it has the same origin as the host page, iFramed content from another source that you do not control can not be targeted.