ArcGIS Experience Builder (ExB) can be integrated with other apps to share data and enhance user experience. This topic provides guidance on how to achieve this integration using URL parameters and postMessage.
Methods for sharing data
When you share data between an Experience Builder app and another app, there are two main approaches:
- URL parameters: Pass data into the ExB app. For details, see the URL parameters documentation.
- postMessage: Pass data in both directions between the ExB app and the other app.
URL parameters method
When you embed an ExB app in another app using an iframe, you can pass data to the ExB app using URL parameters. For example, you can use the ?data= URL parameter to pass data into the ExB app. The ExB app can read the URL parameters and use the data accordingly.
postMessage method
An ExB app can both send and receive messages. Each message includes a type property to identify the message and a payload containing the actual data.
To integrate an ExB app with another app using postMessage, embed the ExB app in the other app using an iframe, or embed the other app in the ExB app using the Embed widget.
When an ExB app is embedded in another app, it does not post messages by default. To enable this behavior, add the ?post URL parameter to the embedded ExB app URL.
When the ExB app embeds another app, add the ?listen URL parameter to the embedded app URL so it can receive ExB app messages.
For security considerations, the ExB app:
- In ArcGIS Online edition, only posts messages to
*.arcgis.comor listens to messages from*.arcgis.com. - In Enterprise edition, only posts messages to apps under the same domain or listens to messages from apps under the same domain.
- In Developer edition, can post or listen to messages from domains listed in
window.trusted.Origins
Add the following code in index.html to set window.trusted:
<script>
window.trustedOrigins = ['https://www.example.com'];
</script>Supported messages from Experience Builder app (Outgoing messages)
Below are the messages that an ExB app can post to the other apps. The other apps can listen to these messages and handle them accordingly.
Authentication
When the ExB app is embedded with the ?arcgis-auth-origin= URL parameter, it posts the following message to request credentials from the parent app.
{
"type": "arcgis:auth:requestCredential"
}When the ExB app receives a credential request, it posts the following message.
{
"type": "arcgis:auth:credential",
"credential": { }
}Navigation and windows
When a page is changed in the ExB app, the following message is posted.
{
"type": "exb:pageChange",
"pageId": "", // the current display page
}When a view is changed in the ExB app, the following message is posted.
{
"type": "exb:viewChange",
"views": [{
"sectionId": "",
"viewId": ""
}], // the current display views in the changed sections
}When a window is opened in the ExB app, the following message is posted.
{
"type": "exb:windowOpen",
"windowId": "",
}When a window is closed in the ExB app, the following message is posted.
{
"type": "exb:windowClose",
"windowId": "",
}Data records and filters
When the selection of data records changes in the ExB app, the following message is posted.
{
"type": "exb:dataRecordsSelectionChange",
"selection": {
"dataSourceId": "",
"recordIds": []
} // the current selected records in the changed data source
}When the filter of a data source is changed in the ExB app, the following message is posted.
{
"type": "exb:dataSourcesFilterChange",
"filter": {
"dataSourceId": "",
"where": "",
"geometry": {} // The JSON of the [Maps SDK Geometry](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Geometry.html#toJSON)
} // the current filters of the changed data sources
}When some data records are created in the ExB app, the following message is posted.
{
"type": "exb:recordsCreate",
"records": [{
"dataSourceId": "",
"recordIds": [],
}]
}When some data records are updated in the ExB app, the following message is posted.
{
"type": "exb:recordsUpdate",
"records": [{
"dataSourceId": "",
"recordIds": [],
}]
}When some records are removed in the ExB app, the following message is posted.
{
"type": "exb:recordsRemove",
"records": [{
"dataSourceId": "",
"recordIds": [],
}]
}Map and extent
When the map extent changes in the ExB app, the following message is posted.
{
"type": "exb:extentChange",
"mapWidgetId": "",
"extent": {}, // The JSON of [Maps SDK Extent](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Extent.html#toJSON)
"viewpoint": {}, // The JSON of [Maps SDK ViewPoint](https://developers.arcgis.com/javascript/latest/api-reference/esri-Viewpoint.html#toJSON)
}Supported messages sent to Experience Builder app (Incoming messages)
Authentication
When an app needs to get credentials from the ExB app, it can post the following message.
{
"type": "arcgis:auth:requestCredential"
}Navigation and windows
When an app needs to change the page in the ExB app, it can post the following message.
{
"type": "exb:changePage",
"pageId": ""
}When an app needs to change the view in the ExB app, it can post the following message.
{
"type": "exb:changeView",
"views": [{
"sectionId": "",
"viewId": ""
}]
}When an app needs to open the window in the ExB app, it can post the following message.
{
"type": "exb:openWindow",
"windowId": ""
}- When an app needs to close the window in the ExB app, it can post the following message.
{
"type": "exb:closeWindow",
"windowId": ""
}Data records and filters
When an app needs to select records in the ExB app, it can post the following message.
{
"type": "exb:selectRecords",
"selection": {
"dataSourceId": "",
"recordIds": []
}
}When an app needs to filter the data source in the ExB app, it can post the following message.
{
"type": "exb:filterDataSource",
"filter": {
"dataSourceId": "",
"where": "",
"geometry": {} // The JSON of the [Maps SDK Geometry](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Geometry.html#toJSON)
}
}Map and extent
When an app needs to change the map extent in the ExB app, it can post the following message.
{
"type": "exb:changeExtent",
"mapWidgetId": "",
"extent": {}, // The JSON of [Maps SDK Extent](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Extent.html#toJSON)
"viewpoint": {}, // The JSON of [Maps SDK ViewPoint](https://developers.arcgis.com/javascript/latest/api-reference/esri-Viewpoint.html#toJSON)
}Note: Both extent and viewpoint are optional. If viewpoint is set, extent is ignored.
When an app needs to make the map zoom to a location in the ExB app, it can post the following message.
{
"type": "exb:zoomTo",
"mapWidgetId": "",
"geometry": {}, // The JSON of the [Maps SDK Geometry](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Geometry.html#toJSON)
"scale": 10 // Optional map scale.
}When an app needs to make the map pan to a location in the ExB app, it can post the following message.
{
"type": "exb:panTo",
"mapWidgetId": "",
"geometry": {} // The JSON of the [Maps SDK Geometry](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Geometry.html#toJSON)
}Sample code
Embedding an ExB app in another app using iframe and communicate through postMessage
<!DOCTYPE html>
<html>
<script>
// listen to messages from ExB app
window.addEventListener("message", (event) => {
const data = event.data;
if (!data.type || !data.type.startsWith("exb:")) {
return;
}
// you can handle different types of messages here, for example:
if (data.type === "exb:pageChange") {
// handle page changed message
} else {
// handle other types of messages
}
});
// send message to ExB app
const exbApp = document.getElementById("exbApp");
document.getElementById("page1").addEventListener("click", () => {
exbApp.contentWindow.postMessage({ type: "exb:changePage", pageId: "page_0" }, "*");
});
</script>
<body>
<iframe id="exbApp" width="1500px" height="1000px" src="[ExB app url]?post_message=true"></iframe>
<div id="receivedMessage" style="white-space: pre-wrap; margin-top: 20px;"></div>
<button id="page1">Go to Page 1</button>
</body>
</html>Embedding another app in an ExB app using the Embed widget and communicate through postMessage
<!DOCTYPE HTML>
<html lang="en-us" style="width: 100%">
<body style="width: 100%">
<script>
function onMessage(evt){
// handle messages from ExB app here
}
window.addEventListener("message", onMessage, false);
</script>
</body>
</html>