Embed an ArcGIS app in an <iframe>

Iframes are a web technology used to embed content from one website into another website or HTML page. The HTML tag <iframe> is used for this purpose, and can be created with a wide variety of configurations and properties.

When integrating ArcGIS interfaces or functionality into other business systems, one common pattern is to embed a web app, such as one from ArcGIS Instant Apps, ArcGIS Experience Builder, or another app built with the Maps SDK for JavaScript, into another business system application through the use of an iframe.

This may involve writing code or HTML that explicitly defines an <iframe> or the other system may have a pattern like an embed widget or tool that handles the iframe process, which may impose additional restrictions on the iframe, or control which iframe tag attributes can be set.

Examples of workflows that can be supported with this pattern include:

• Embed a locator map into a larger web page, to find store locations or common geographic features

• Create an editable web map and app, and embed it into another larger data collection or configuration process that is form-based or built using another technology

• Display an ArcGIS Survey123 form using URL parameters, as part of a website or application that collects data or participates in a broader workflow.

This capability and its best practices also apply to scenarios where ArcGIS applications are embedded in other ArcGIS applications.

Integration patterns in ArcGIS

Full support

Partial support

In a remote system, an <iframe> can be used to embed applications from ArcGIS Online, ArcGIS Enterprise, or custom applications built with the ArcGIS Maps SDK for JavaScript.

Use URL parameters

Many ArcGIS web apps support a set of on-load configurable properties defined through URL parameters, such as https://my.domain.com/portal/home/apps/viewer.html?center=-54,120&zoom=5 (center the app at those coordinates and zoom to scale level 5). Using this integration pattern, it is common to dynamically set these URL parameters (controlling how the iframe application will load) using properties from the parent or business system application. For example, if the user is viewing a record in a non-ArcGIS system with an identifier of BD1245 in the parent application, when the iframe is defined it may include a URL such as ../my-app.html?featureID=BD1245, so that the app loads with the data of interest already visible and focused in the application.

Best practices for <iframe> embeds

Historically, iframes have been a popular technology that also introduced a wide array of security challenges. This has led to a variety of browser limitations that are imposed on iframes, which can restrict functionality or ease of use across systems. A few key challenges include:

• Single sign-on is complicated. Browser standards often block the re-use of existing session cookies in an <iframe>, unless the domain of the <iframe> matches the domain of the parent content. This means that a user often must authenticate to the ArcGIS system that is embedded in the <iframe>, which will require a login interaction. If both the parent of the frame and the frame itself are authenticated through the same identity provider, users may expect a single sign on experience and be dissatisfied with a second login requirement. Some enterprise identity providers may also block the use of their sign-in dialog in an iframe, and other approaches such as carefully-crafted Content-Security-Policy headers may be required.
• To best address this issue, use the same domain (such as .domain.com) for both parent and iframe site, use the same single sign-on provider, and allow the app to automatically forward users to login as necessary.

• File downloads or uploads may be blocked. Browser security may block download of files from iframes, with a download link or download button in an embedded app not reporting an error or failure, but simply failing to download a file such as an export from a feature table. This category of issue is usually reported through a browser JavaScript console message.

• Screen size may negatively affect user interfaces. Iframes are frequently defined as a constant frame size in pixels, and apps that will be embedded should be designed for that expected view size. If the parent application can intelligently scale the iframe to the user’s screen resolution, users with larger screens may have a responsive experience, but a fixed size iframe will result in a small embedded window that may have a negative user experience. Embedded apps should be designed so all the primary UI elements and interactions can be accomplished in the provided screen area.

• Communications between the iframe and parent window are usually limited. While some <iframe> patterns support communications between the parent window and the <iframe> through protocols or patterns like postMessage, most ArcGIS applications do not provide this capability, so interactions in the iframe application do not affect the parent window, or vice versa.