Use URL parameters

Note:

As of the February 2024 release of Experience Builder, 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 February 2024 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 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

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-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_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=true

https://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=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_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:

If the URL contains the data_s parameter and any of the Map widget parameters, the Map widget parameters have the higher priority.

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

Zoom or pan the map to selected features

You can use the zoom_to_selection parameter to zoom or pan all Map widgets in the app to selected features. To make maps zoom to selected features, add zoom_to_selection=true to the URL. To make maps pan to selected features, add zoom_to_selection=false.

The zoom_to_selection parameter works with all three selection types: id, geometry, and where. The following are examples:

https://experience.arcgis.com/experience/<AppId>/#data_s=id:<data source ID>:<OBJECTID>&zoom_to_selection=true

https://experience.arcgis.com/experience/<AppId>/#data_s=id%3AdataSource_1-csv_905%3A77&zoom_to_selection=true

You can use the settings under Manage URL status to make this parameter appear in the URL when users select data.

Note:

Imagery layers only support selecting by id.

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_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

Note:

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>"%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 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

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>