Intro to iFrames

iFrames, also known as Inline Frames, are essentially a web page within a web page. They're used to display content from other web pages within your web page — whether it's to embed forms, media, reports, or other materials.

Important Note: 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.

When using Appcues on a page that includes iFrames, you have 2 options:

1. Install Appcues on both the outer web page and within the iFrame web page 
   This is our recommendation, because it will allow you to use all Appcues experience types both on the outer page and within the iFrame.
    
2. Install Appcues on only the outer web page
   This option will allow you to build Appcues Flows within the iFrame, as well as build flows that span from the outer frame into the iFrame; however, it will limit your ability to use other Appcues experiences within the iFrame (such as Pins, Banners, and Click-to-Track Events). These other experiences will only be supported on the outer page where Appcues is installed. 
   If you choose to only install on the outer frame, jump to the instructions for building Flows across an iFrame.

Guide for building and publishing within an iFrame

This section is applicable if you’ve installed Appcues within your iFrame pages.

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 can 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

This guide is applicable whether you have installed Appcues within the iFrame or only on the outer page.

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.

7. Can you have a navigation step within an iFrame?

Flows that are built and targeted within an iFrame can use navigation steps and the navigation actions will work like a normal flow, just within the context of the iframe.
Flows that are built across an iFrame can have navigation steps for the outside application. For steps that are targeting elements within an iFrame navigation actions in the iframe are not supported, however a user can still click the element in the iFrame for regular redirect behavior and to progress the flow.

8. Can you use the builder to identify selectors in an iframe if the outer application is a different origin?

Due to the browser cross-origin restriction the builder can not be used to detect elements in an iFrame when the outer application is a different origin. In cases like this we recommend using the iFrame in new tab extension to open the iFrame in a new tab and using the builder in the context of that tab to build the flow and generate selectors.