The Embed widget allows you to embed website content using a URL or code for additional custom functionality.
Examples
Use this widget to support app design requirements such as the following:
- You have a requirement to provide additional information from a website based on the selection of a feature. The feature layer contains a field with URLs to websites that you want to embed once a user selects a feature on the map or clicks a button to see more information for that feature.
- You want to embed a dashboard in your app and allow users to append a URL parameter to the end of the web experience URL to change the current view of the dashboard (such as to show data for a specific region).
- You want to embed content using HTML code (such as a website) or copy the code from a sample (such as point clustering).
Usage notes
The following is an example of how to use custom code to embed an iframe:
<iframe width="100%" height="600px" frameborder="0" scrolling="yes" marginheight="0" marginwidth="0" src="https://developers.arcgis.com/"></iframe></div>Note:
If you choose to display a PDF directly in the Embed widget, some users may not be able to view it in certain browsers for security reasons.
To create a dynamic URL using URL parameters, save and reload your app with the URL parameter you want to use, so you can select a corresponding key in the URL info window. At run time, the Embed widget finds and matches the name of the specified URL info with the URL parameters added to the host app's URL and resolves the URL using the corresponding value to display the embedded app.
Settings
The Embed widget includes the following settings:
- Embed by—Choose to embed by URL or code.
- URL—Embed a website with a static URL or use the following options to form a dynamic URL:
Note:
Only HTTPS URLs are supported. For security, the embedded app is constrained by the same origin policy. For domains other than *.arcgis.com and *.esri.com, the sandbox attribute is automatically added.
- Connect to data—Select a layer as the data source (added from web maps, web scenes, direct layer, or through URL) and click the Data button to select an attribute that contains URLs or to add to an existing URL as parameters. Use the Label field to display a description in the widget when it is not populated by the contents of a URL in the data.
- URL info—Obtain URL parameters that you add as a suffix to your app URL in the builder. Configure a dynamic URL to pass URL parameters from the Embed widget to the embedded app so users can add URL parameters to the web experience URL at run time to control what appears in the embedded app.
Note:
For information about URL parameters supported by the embedded app, refer to the respective documentation, such as for ArcGIS Dashboards and ArcGIS Web AppBuilder.
- Code—Add your own custom code to embed third-party elements in your experience. It supports HTML, CSS in <style> tags, and JavaScript in <script> tags.
Tip:
If you want to embed a complex HTML page that exceeds the 8 KB size limit imposed for performance reasons, deploy it to your own server and embed by URL instead.
Note:
When you embed by code, the sandbox attribute is automatically added without the allow-same-origin directive. This allows the embedded content to run JavaScript and read its own cookie or local storage information, but it can't access the Experience Builder app DOM, cookie, local storage, and so on.
- URL—Embed a website with a static URL or use the following options to form a dynamic URL:
- Auto refresh—Set a custom time interval (in minutes) to automatically refresh the embedded content in the Embed widget. The minimum value you can set is 0.2 minutes (12 seconds).
Configure a dynamic URL
Complete the following steps to obtain URL parameters from your web experience that you can pass to an embedded app:
- Add an Embed widget and save.
- In the address bar of the browser window, add the URL parameter to your web experience URL and press Enter to reload the page.
Tip:
Because the builder already includes the app ID parameter, add the URL parameter using an ampersand (such as &state=) instead of a question mark.
Once the builder reloads with the URL parameter, the URL info button displays its key to build a dynamic URL.
- In the Embed by URL input box, paste the URL for the app you want to embed.
- At the end of the embed URL, type the URL parameter (such as ?state=).
- Click the URL info button and select the corresponding key to complete the dynamic URL.
The following is an example dynamic URL for an embedded dashboard:
https://<your portal url>/apps/opsdashboard/index.html#/<id>?state={appURL.search.state}
Share authentication
Some web applications prompt users to sign in with an ArcGIS account. An app might require login because of its share settings, because the app includes widgets that use premium content, or for other reasons.
If you want to embed an ArcGIS web app in your Experience Builder app, and both require login, you can add the arcgis-auth-origin and arcgis-auth-portal URL parameters to share authentication between both apps so users only need to sign in once.
To embed a private Experience Builder app in another Experience Builder app, use ?arcgis-auth-origin= to define the host app domain URL for authentication. The following is an example:https://<orgA.arcgis.com>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>
To embed a JavaScript API-based app, such as a Web AppBuilder app, use the ?arcgis-auth-origin= for the host app domain authentication and ?arcgis-auth-portal= for the JavaScript API based app's domain authentication. The following is an example:https://<orgA.arcgis.com>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>&arcgis-auth-portal=<orgA URL>