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.
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 Online 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=fr
https://experience.arcgis.com/experience/<AppId>/?locale=fr-ch
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-4
https://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_block1
To 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-2
https://experience.arcgis.com/experience/<AppId>/?views=v1
Open 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
parameter. Add the following URL to the host web page to disable the movement behavior. By default, disable
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
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=true
https://experience.arcgis.com/experience/<AppId>/?draft=1
Open print preview
To activate print preview mode, use print
.
https://experience.arcgis.com/experience/<AppId>/?print_preview=true
https://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
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:Use dark colors for code blocks Copy 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:Use dark colors for code blocks Copy 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:Use dark colors for code blocks Copy 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%3
and before %3
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.
Filter data sources
To directly filter a data source, use data
. The filter format is a standard WHERE clause syntax. To filter multiple data sources, use the format [
.
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 field
):
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
.
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 (#
).
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
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_4
Center 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.0800833
Define 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:45
Define 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%7D
Define visibility for map layers
To define layer visibility for a map's layers, use layer
.
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
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 search
parameter shows what text the user entered to perform a search. The following is an example URL with the search
parameter:
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D
Show 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
service
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:Enabled List Use dark colors for code blocks Copy 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"
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::{"config Id" :" <Source ID >"} Use dark colors for code blocks Copy 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 magic
associated with the suggestion. A magic
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
Send users to an organization sign-in page
In general, when users attempt to access a private Experience Builder app on ArcGIS Online, they are directed to the main ArcGIS Online sign-in page. To send users to your organization's sign-in page instead, use org
followed by your organization's short name.
https://experience.arcgis.com/experience/<AppId>/?org=<yourorgshortname>