Note:
As of the ArcGIS Enterprise 11.3 release, preserved URL delimiters that are not in parameter values must be in plain text and cannot be encoded. URLs with encoded delimiters created before the ArcGIS Enterprise 11.3 release no longer work. You must change them to plain text.
In Experience Builder you can add URL parameters to your apps. You can use URL parameters to enhance an experience by making the URL set a locale, direct to a specific page, activate the print preview, and more.
Parameters are added to the end of the URL and are formatted as a key-value pair connected with an equal sign. Experience Builder apps support parameters that are query strings and fragments, meaning they start with a question mark (?) or hashmark (#). To include multiple parameters, you must separate them with ampersands (&). Experience URLs with parameters use the following structure: https://<domain>/experience/<AppID>/[?<param1=value>&<param2=value>#<param3=value>...]
The following is an example:https://experience.arcgis.com/experience/<AppId>?locale=fr#data_s=id%3AdataSource_3-World_Cities_8506%3A1
An experience's URL can include one or more of the parameters listed below.
Caution:
Throughout this topic, square brackets ([]) indicate that the enclosed parameter or value is optional. Do not add the square brackets to a URL.
General parameters
The subsections below describe general URL parameters.
Switch locale
To switch the app language, use the locale parameter and a two-letter ISO 639-1 language code. Experience Builder supports all the same languages that ArcGIS Enterprise supports, which includes the following language codes: ar, bg, bs, ca, cs, da, de-at, de-de, de-ch, el, en-au, en-ca, en-gb, en-us, es-es, es-mx, et, fi, fr-fr, fr-ch, he, hr, hu, id, it-it, it-ch, ja, ko, lt, lv, nb, nl, pl, pt-br, pt-pt, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-cn, zh-hk, and zh-tw.
To use an Experience Builder app in French and Switzerland French, you can append locale=fr to the URL, such as in the following examples:https://experience.arcgis.com/experience/<AppId>/?locale=frhttps://experience.arcgis.com/experience/<AppId>/?locale=fr-ch
Note:
If you only assign a language without a detailed locale, such as fr instead of fr-ch or fr-fr, you may not obtain an expected date or number format. This is because different locales that speak the same language may have different notations for dates and numbers, such as the United States (en-us) and the United Kingdom (en-gb).
Define the web map or web scene
To display a map or scene in a Map widget, use webmap or webscene followed by the map or scene's item ID.https://experience.arcgis.com/builder/?webmap=<ItemID>https://experience.arcgis.com/builder/?webscene=<ItemID>https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544
Go to a page
To direct to a specific page, use page followed by the page name. In ArcGIS Online Experience Builder apps, the page parameter is not part of a query string and does not follow a question mark. It is added in the URL path, as in the following examples:https://experience.arcgis.com/experience/<AppId>/page/Page-4https://experience.arcgis.com/experience/<AppId>/page/{xxxHome}/
Go to a block
To direct to a specific block, use block followed by the blockID. The following is an example:
https://experience.arcgis.com/experience/<AppId>/?block_id=layout1_block1To find a block's blockID, you can set a link to the block on a button, image, or any other widget that supports Set link. When you preview the app and click the linked widget, the blockID appears in the URL.
Go to a view
To direct to a specific active section view, use views followed by a view label such as v1 or View 1.
https://experience.arcgis.com/experience/<AppId>/?views=View-2https://experience.arcgis.com/experience/<AppId>/?views=v1Open a window
To direct to a specific active window, use dlg followed by a window ID or label.https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1
Control window focus
To embed an Experience Builder app with splash windows or page windows without the app automatically going to those windows, you can use the disable_window_focus parameter. Add the following URL to the host web page to disable the movement behavior. By default, disable_window_focus is false.https://experience.arcgis.com/experience/<AppId>/?disable_window_focus=true
To control window focus for a specific window, use dlg followed by a window ID or label and the disable_window_focus parameter, as in the following example:https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1&disable_window_focus=true
View draft mode
Whenever you preview an app, the draft parameter is automatically added. It allows you to obtain item resources for unpublished apps.https://experience.arcgis.com/experience/<AppId>/?draft=truehttps://experience.arcgis.com/experience/<AppId>/?draft=1
Open print preview
To activate print preview mode, use print_preview.https://experience.arcgis.com/experience/<AppId>/?print_preview=truehttps://experience.arcgis.com/experience/<AppId>/?print_preview=1
Data-related parameters
The subsections below describe data-related URL parameters.
Select data
To select data records, use the data_s parameter, which follows a hashmark (#).
Each data source in an app has its own data source ID. When you select a data record, the data source's ID is added to the app's URL, along with the selection type and selection condition. If you have multiple selections, they are separated by commas (,). The following is an example:https://experience.arcgis.com/experience/<AppId>/#data_s=<selection type>:<data source ID>:<selection condition>,<selection type>:<data source ID>:<selection condition>,...
There are three selection types: id, geometry, and where.
- When the selection type is id, you are selecting features by their recordIDs. If you are selecting multiple records from the same data source, recordIDs are separated by plus signs (+). The following is an example:
https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3 - When the selection type is geometry, you are selecting features based on their location relative to other features. Multiple data source IDs are connected by tildes (~). The following is an example:
https://experience.arcgis.com/experience/<AppId>/#data_s=geometry:widget_1-dataSource_1-1871234a785-layer-2~widget_1-dataSource_1-1871234a785-layer-3:<the geometry JSON> - When the selection type is where, you are selecting features based in their attributes. The following is an example:
https://experience.arcgis.com/experience/<AppId>/#data_s=where:widget_1-dataSource_1-1871234a785-layer-2:a>1
You can use this parameter to find a layer's specific data source ID. For example, you can add a List widget and connect it to a layer, preview the app, and select any record in the list. The URL populates similar to the following example:https://experience.arcgis.com/experience/<AppID>/#data_s=id%3AdataSource_3-World_Cities_8506%3Axxxxxx
The value after id%3A and before %3Axxxx is the layer's data source ID. Knowing the ID, you can use it with other parameters to filter the data source or change versions.
Note:
Experience Builder previously used the ?data_id parameter to select data. That parameter is currently still supported but will soon be deprecated.
Filter data sources
To directly filter a data source, use data_filter. The filter format is a standard WHERE clause syntax. To filter multiple data sources, use the format [<dsId:filter>,<dsId:filter>].
Caution:
Some filters may include characters that are preserved URL delimiters (for example, "&", "=", "'", and "?"). To ensure that the URL interprets values correctly, you must URL-encode unsafe characters by replacing them with a % character followed by the value corresponding to their UTF-8 hexadecimal equivalent.
The following table lists common characters that you must encode if they are in parameter values:
| Unsafe character | Encoded value |
|---|---|
SPACE | %20 |
# | %23 |
% | %25 |
& | %26 |
' | %27 |
, | %2C |
: | %3A |
= | %3D |
? | %3F |
Note:
You only need to encode unsafe characters in parameter values. If a character is acting as a URL delimiter, meaning it is not in a parameter value, it must be in plain text and cannot be encoded.
The following is a URL with an un-encoded filter, which will not generate the expected result:http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name='Even&Odd'
The following URL is a correctly encoded version of the URL above. Note that some characters from the table above are not encoded. This is because they are acting as URL delimiters.http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27
The following is another example URL with two encoded filter parameters (objectid=1 and fieldA>2):https://experience.arcgis.com/experience/<AppId>/?data_filter=ds1:objectid%3D1,ds2:fieldA%3E2
Change the geodatabase version of a data source
To change the geodatabase version of a data source, use data_version.https://experience.arcgis.com/experience/<AppId>/?data_version=<dsId:version>,<dsId:version>https://experience.arcgis.com/experience/<AppId>/?data_version=dsId1:v1, dsID2:v1
Widget-related parameters
You can use an app's URL to affect widget behaviors by adding widget URL parameters. While different parameters are implemented through various methods, they generally adhere to the same syntax:https://experience.arcgis.com/experience/<AppId>#widget_1=param1:<value>,param2:<value>&widget_2=param1:<value>&...
Widget parameters begin in a URL with hashmarks (#) and are chained together with ampersands (&). If you have multiple parameters affecting the same widget, they are separated by commas.
Some values may include characters that are preserved URL delimiters (for example, "&", "=", "'", and "?"). To ensure that the URL interprets values correctly, you must URL-encode unsafe characters by replacing them with a % character followed by the value corresponding to their UTF-8 hexadecimal equivalent. URL delimiters outside of parameter values must be in plain text and cannot be encoded.
For example, the center parameter in the following will not function correctly because two of the comma characters need to be encoded:https://experience.arcgis.com/experience/<AppId>#map_1=center:-100,100,102100,rotation:45
The following is the correctly written version of the above URL:https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45
Map widget parameters
The subsections below describe map-related URL parameters. You can use the settings under Manage URL status to make these parameters appear in the URL when the user interacts with the Map widget. All of the Map widget's parameters follow hashmarks (#).
Note:
The Map widget's center, scale, and rotation parameters only work with web maps, not web scenes.
Define the web map or web scene for when a Map widget first loads
If your Map widget contains multiple web maps or web scenes, you can define which one is active when the app loads using active_datasource_id followed by the desired item's data source ID. The following are examples:
https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4Center a map
To center a map on a particular location, use center followed by the desired coordinates and the desired coordinate system's well-known ID (WKID). The following are examples:https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=center:<x,y,wkid>https://experience.arcgis.com/experience/<AppId>#map_1=center:-10373125.398783844%2C4598516.55871741%2C102100
Define the map scale
To define the map scale, use scale followed by a scale value. The following are examples:
https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833Define the map rotation
To define the map rotation, use rotation followed by a number of degrees. The following are examples:
https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45Define the map viewpoint
To define the viewpoint, which is the location or camera position from which to view the map or scene, use viewpoint. If your map widget contains multiple maps or scenes, the viewpoint parameter affects all of them.
Viewpoints and their properties are typically written in JSON format, as in the following example:
{
"rotation": 0,
"scale": 19966005.903731048,
"targetGeometry": {
"spatialReference": {
"latestWkid": 3857,
"wkid": 102100
},
"x": -9870655.016044471,
"y": 4724533.527708739
}
}To define a specific viewpoint using the URL, you must encode all of those properties typically written in JSON format into the URL. The following is an example:
https://experience.arcgis.com/experience/<AppId>#map_1=viewpoint:%7B"rotation"%3A0%2C"scale"%3A24387741.012671936%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-10078461.002935613%2C"y"%3A4523117.553838721%7D%7DNote:
The center, scale, and rotation parameters have higher priorities than the viewpoint parameter and will override it if you use multiple parameters related to a web map.Note:
Map extent changes caused by message actions have a higher priority than extent changes caused by URL parameters. For example, if you try to open a Map widget to predefined extents using the above URL parameters, but the Map widget is also configured as the target of the Record selection changes trigger and Pan to or Zoom to message actions, then the extents associated with the message actions supersede the extents you set with URL parameters.
Define visibility for map layers
To define layer visibility for a map's layers, use layer_visibility.
Layer visibility is typically written in JSON format, as in the following example:
{
"widget_1-dataSource_1": {
"widget_1-dataSource_1-187938b7328-layer-2": false
},
"widget_1-dataSource_4": {
"widget_1-dataSource_4-18a690b433a-layer-4": false
}
}To make layers in your map visible or hidden using the URL, you must encode all of the information into the URL after the layer_visibility parameter. The following is an example:https://experience.arcgis.com/experience/<AppId>#map_1=layer_visibility:%7B%22widget_1-dataSource_1%22%3A%7B%22widget_1-dataSource_1-187938b7328-layer-2%22%3Afalse%7D%2C%22widget_1-dataSource_4%22%3A%7B%22widget_1-dataSource_4-18a690b433a-layer-4%22%3Afalse%7D%7D
Search widget parameters
The subsections below describe search-related URL parameters. You can use the settings under Manage URL status to make these parameters appear in the URL when the user performs a search. Search widget parameters follow hashmarks (#).
Show the search input
The searchText parameter shows what text the user entered to perform a search. The following is an example URL with the searchText parameter:
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7DShow the search source
When the user performs a search using only some of the available search sources, one of the two following parameters appear in the URL:
- If at least one search source is unchecked in the widget's drop-down menu at run time, the serviceEnabledList parameter appears and defines which search sources are checked. This parameter is hidden when all search sources are checked. The following is an example encoded URL:
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D - If the user clicks a search suggestion to apply a search, the "status":{"configId":"<SourceID>"} parameter appears and defines the unique search source being used in the current search. Both the search input and the search source appear in the URL. The following is an example encoded URL:
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D
If the user clicks a search suggestion from a locator source, the URL displays the magicKey associated with the suggestion. A magicKey is a unique ID that links a suggestion to a specific address or place. The following is an example of search properties and parameters written in JSON format:{
"searchText": "<text>",
"status":{
"configId": "<SourceID>",
"magicKey": "<key>"
}
}
The following is an example of the same properties and parameters above written in an encoded URL:https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%2C"magicKey"%3A"<key>"%7D%7D
Login-related parameters
The subsections below describe login-related URL parameters.
Share authentication through an Embed widget
Some web apps prompt users to sign in with an ArcGIS account. An app can require users to sign in because of its share settings, because the app includes widgets that use premium content, or for other reasons.
To embed an ArcGIS web app in an Experience Builder app when both require users to sign in, 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://<orgdomain>/experience/<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 ?arcgis-auth-origin= for the host app domain authentication and ?arcgis-auth-portal= for the JavaScript for the ArcGIS portal from which the JavaScript API-based app needs authentication. The following are examples:https://<orgdomain>/apps/webappviewer/index.html?id=<appID>&arcgis-auth-origin=<your host app domain, such as https://localhost:3001>&arcgis-auth-portal=<orgA URL>https://www.arcgis.com/apps/dashboards/index.html#/<appID>?arcgis-auth-origin=https://experience.arcgis.com&arcgis-auth-portal=https://<myorg>.maps.arcgis.com