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%3A1An 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=frhttps://experience.arcgis.com/experience/<AppId>/?locale=fr-chDefine 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/experience/<AppId>/?webmap=<ItemID>https://experience.arcgis.com/experience/<AppId>/?webscene=<ItemID>https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544Go 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-1Control 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=trueTo 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=trueView 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=1Open print preview
To activate print preview mode, use print_ .
https://experience.arcgis.com/experience/<AppId>/?print_preview=truehttps://experience.arcgis.com/experience/<AppId>/?print_preview=1Data-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%3AxxxxxxThe 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.
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 [<ds .
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. Only unsafe characters in parameter values must be encoded.
http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27The 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%3E2Change 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:v1Widget-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 # and are chained together with & s. If you are 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.
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:45The following is the correctly written version of the above URL.
https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45Map 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_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%2C102100Define 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:
{
"viewpoint": {
"rotation": 0,
"scale": 18489297.737236,
"targetGeometry": {
"spatialReference": {
"latestWkid": 3857,
"wkid": 102100
},
"x": -11170362.895452116,
"y": 4783779.707603601
}
},
"extent": {
"spatialReference": {
"latestWkid": 3857,
"wkid": 102100
},
"xmin": -15472850.343566973,
"ymin": 1819246.0025921133,
"xmax": -6867875.447337259,
"ymax": 7748313.412615089
}
}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=map_state:%7B"viewpoint"%3A%7B"rotation"%3A0%2C"scale"%3A18489297.737236%2C"targetGeometry"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"x"%3A-11170362.895452116%2C"y"%3A4783779.707603601%7D%7D%2C"extent"%3A%7B"spatialReference"%3A%7B"latestWkid"%3A3857%2C"wkid"%3A102100%7D%2C"xmin"%3A-15472850.343566973%2C"ymin"%3A1819246.0025921133%2C"xmax"%3A-6867875.447337259%2C"ymax"%3A7748313.412615089%7D%7DDefine 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%7DSearch 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>"%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
serviceparameter 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":{"configparameter 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: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%7DLogin-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 API based app's domain 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/opsdashboard/index.html#/<appID>?arcgis-auth-origin=https://experience.arcgis.com&arcgis-auth-portal=https://<myorg>.maps.arcgis.comSend 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>