Usar parámetros de URL—ArcGIS Experience Builder

Nota:

A partir de la versión de febrero de 2024 de Experience Builder, los delimitadores de URL conservados que no estén en los valores de los parámetros deben estar en texto sin formato y no pueden codificarse. Las URL con delimitadores codificados creadas antes de la versión de febrero de 2024 ya no funcionan. Debe cambiarlas a texto sin formato.

En Experience Builder, puede agregar parámetros de URL a sus aplicaciones. Puede utilizar parámetros de URL para mejorar una experiencia haciendo que la URL establezca una configuración regional, dirija a una página específica, active la vista previa de impresión, etc.

Los parámetros se agregan al final de la URL y se formatean como un par de clave-valor conectado con un signo igual. Las aplicaciones de Experience Builder admiten parámetros que sean fragmentos y cadenas de caracteres de consulta, es decir, que comiencen con un signo de interrogación (?) o de almohadilla (#). Para incluir varios parámetros, debe separarlos con símbolos et (&). Las URL de experiencias con parámetros utilizan la siguiente estructura:

 https://<domain>/experience/<AppID>/[?<param1=value>&<param2=value>#<param3=value>...]

A continuación, encontrará un ejemplo:

https://experience.arcgis.com/experience/<AppId>?locale=fr#data_s=id%3AdataSource_3-World_Cities_8506%3A1

La URL de una experiencia puede incluir uno o varios de los parámetros que se enumeran a continuación.

Precaución:

En este tema, los corchetes ([]) indican que el parámetro o valor incluido dentro es opcional. No agregue los corchetes a una URL.

Parámetros generales

Las siguientes subsecciones describen parámetros generales de la URL.

Cambiar la configuración regional

Para cambiar el idioma de la aplicación, utilice el parámetro locale y un código de idioma ISO 639-1 de dos letras. Experience Builder admite los mismos idiomas que admite ArcGIS Online, lo cual incluye los siguientes códigos de idioma: 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 y zh-tw.

Para utilizar una aplicación de Experience Builder en francés y francés de Suiza, puede incorporar locale=fr a la URL, como en los siguientes ejemplos:

https://experience.arcgis.com/experience/<AppId>/?locale=fr

https://experience.arcgis.com/experience/<AppId>/?locale=fr-ch

Nota:

Si solo asigna un idioma sin una configuración regional detallada, como fr en lugar de fr-ch o fr-fr, puede que no obtenga un formato de número o fecha esperado. Esto se debe a que diferentes configuraciones regionales que hablan el mismo idioma pueden tener diferentes notaciones para fechas y números, como por ejemplo Estados Unidos (en-us) y Reino Unido (en-gb).

Definir el mapa web o la escena web

Para mostrar un mapa o escena en un widget Mapa, utilice webmap o webscene seguido del Id. del elemento del mapa o escena.

https://experience.arcgis.com/builder/?webmap=<ItemID>

https://experience.arcgis.com/builder/?webscene=<ItemID>

https://experience.arcgis.com/builder/?webmap=3582b744bba84668b52a16b0b6942544

Ir a una página

Para dirigir a una página específica, utilice page seguido del nombre de la página. En aplicaciones de ArcGIS Online Experience Builder, el parámetro de página no forma parte de una cadena de caracteres de consulta y no va después de un signo de interrogación. Se agrega a la ruta de la URL, como en los siguientes ejemplos:

https://experience.arcgis.com/experience/<AppId>/page/Page-4

https://experience.arcgis.com/experience/<AppId>/page/{xxxHome}/

Ir a un bloque

Para dirigir a un bloque específico, utilice block seguido del blockID. A continuación, encontrará un ejemplo:

https://experience.arcgis.com/experience/<AppId>/?block_id=layout1_block1

Para encontrar el blockID de un bloque, puede establecer un vínculo con el bloque en un botón, imagen o cualquier otro widget que admita Definir vínculo. Cuando previsualiza la aplicación y hace clic en el widget vinculado, el blockID aparece en la URL.

Ir a una vista

Para dirigir a una vista de sección activa específica, utilice views seguido de una etiqueta de vista, como v1 o View 1.

https://experience.arcgis.com/experience/<AppId>/?views=View-2

https://experience.arcgis.com/experience/<AppId>/?views=v1

Abrir una ventana

Para dirigir a una ventana activa específica, utilice dlg seguido de un Id. o etiqueta de ventana.

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1

Controlar el enfoque en ventana

Para integrar una aplicación de Experience Builder con ventanas de presentación o ventanas de página sin que la aplicación vaya automáticamente a dichas ventanas, puede utilizar el parámetro disable_window_focus. Agregue la siguiente URL a la página web del host para deshabilitar el comportamiento de movimiento. De forma predeterminada, el valor de disable_window_focus es false.

https://experience.arcgis.com/experience/<AppId>/?disable_window_focus=true

Para controlar el enfoque de la ventana para una ventana específica, utilice dlg seguido por un Id. de ventana o etiqueta y el parámetro disable_window_focus, como en el siguiente ejemplo:

https://experience.arcgis.com/experience/<AppId>/?dlg=Window-1&disable_window_focus=true

Ver el modo borrador

Siempre que previsualice una aplicación, el parámetro draft se agrega automáticamente. Este le permite obtener recursos de elementos para aplicaciones no publicadas.

https://experience.arcgis.com/experience/<AppId>/?draft=true

https://experience.arcgis.com/experience/<AppId>/?draft=1

Abrir la vista previa de impresión

Para activar el modo de vista previa de impresión, utilice print_preview.

https://experience.arcgis.com/experience/<AppId>/?print_preview=true

https://experience.arcgis.com/experience/<AppId>/?print_preview=1

Parámetros relacionados con datos

Las siguientes subsecciones describen parámetros relacionados con datos de la URL.

Seleccionar datos

Para seleccionar registros de datos, utilice el parámetro data_s, que sigue a una almohadilla (#).

Cada fuente de datos de una aplicación tiene su propio Id. de fuente de datos. Al seleccionar un registro de datos, el Id. de la fuente de datos se agrega a la URL de la aplicación, junto con el tipo de selección y la condición de selección. Si tiene varias selecciones, se separan por comas (,). A continuación, encontrará un ejemplo:

https://experience.arcgis.com/experience/<AppId>/#data_s=<selection type>:<data source ID>:<selection condition>,<selection type>:<data source ID>:<selection condition>,...

Hay tres tipos de selección: id, geometry y where.

Cuando el tipo de selección es id, está seleccionando entidades por sus recordID. Si selecciona varios registros de la misma fuente de datos, los recordID se separan con signos más (+). A continuación, encontrará un ejemplo:
```
https://experience.arcgis.com/experience/<AppId>/#data_s=id:widget_1-dataSource_1-1871234a785-layer-2:1+2+3
```
Cuando el tipo de selección es geometry, está seleccionando entidades en función de su ubicación con respecto a otras entidades. Varios Id. de fuentes de datos están conectados por tildes (~). A continuación, encontrará un ejemplo:
```
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>
```
Cuando el tipo de selección es where, está seleccionando entidades en función de sus atributos. A continuación, encontrará un ejemplo:
```
https://experience.arcgis.com/experience/<AppId>/#data_s=where:widget_1-dataSource_1-1871234a785-layer-2:a>1
```

Puede utilizar este parámetro para buscar el Id. específico de la fuente de datos de una capa. Por ejemplo, puede agregar un widget Lista y conectarlo a una capa, obtener una vista previa de la aplicación y seleccionar cualquier registro de la lista. La URL se rellena de forma similar al siguiente ejemplo:

https://experience.arcgis.com/experience/<AppID>/#data_s=id%3AdataSource_3-World_Cities_8506%3Axxxxxx

El valor posterior a id%3A y anterior a %3Axxxx es el Id. de la fuente de datos de la capa. Conociendo el Id., puede usarlo con otros parámetros para filtrar la fuente de datos o cambiar las versiones.

Nota:

Anteriormente, Experience Builder utilizó el parámetro ?data_id para seleccionar datos. Ese parámetro sigue admitiéndose en la actualidad, pero pronto quedará obsoleto.

Filtrar fuentes de datos

Para filtrar directamente una fuente de datos, utilice data_filter. El formato de filtro es una sintaxis estándar de cláusula WHERE. Para filtrar varias fuentes de datos, utilice el formato [<dsId:filter>,<dsId:filter>].

Precaución:

Algunos filtros pueden incluir caracteres que son delimitadores de URL conservados (por ejemplo, "&", "=", "'" y "?"). Para asegurarse de que la URL interpreta valores correctamente, debe codificar con URL caracteres no seguros sustituyéndolos por un carácter de % seguido por el valor correspondiente con su equivalente hexadecimal UTF-8.

En la tabla siguiente se enumeran caracteres comunes que debe codificar si se encuentran en los valores de los parámetros:


Carácter no seguro	Valor codificado
ESPACIO	%20
#	%23
%	%25
&	%26
'	%27
,	%2C
:	%3A
=	%3D
?	%3F

Nota:

Solo necesita codificar caracteres no seguros en los valores de los parámetros. Si un carácter actúa como delimitador de la URL, es decir, no está en el valor de un parámetro, debe estar en texto sin formato y no puede codificarse.

A continuación, se incluye una URL con un filtro no codificado que no generará el resultado esperado:

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name='Even&Odd'

La siguiente URL es una versión correctamente codificada de la URL anterior. Tenga en cuenta que algunos caracteres de la tabla anterior no están codificados. Se debe a que actúan como delimitadores de URL.

http://experience.arcgis.com/experience/<AppID>/?data_filter=dataSource_1:name%3D%27Even%26Odd%27

Lo siguiente es otro ejemplo de URL con dos parámetros de filtro codificado (objectid=1 y fieldA>2):

https://experience.arcgis.com/experience/<AppId>/?data_filter=ds1:objectid%3D1,ds2:fieldA%3E2

Cambiar la versión de geodatabase de una fuente de datos

Para cambiar la versión de geodatabase de una fuente de datos, utilice 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

Parámetros relacionados con widgets

Puede utilizar la URL de una aplicación para influir en los comportamientos del widget agregando parámetros a la URL del widget. Aunque los distintos parámetros se implementan a través de otros métodos, generalmente se adhieren a la misma sintaxis:

https://experience.arcgis.com/experience/<AppId>#widget_1=param1:<value>,param2:<value>&widget_2=param1:<value>&...

Los parámetros del widget comienzan en una URL con marcas de almohadilla (#) y se encadenan con varios símbolos de ampersand (&). Si tiene varios parámetros que afectan al mismo widget, se separan por comas.

Algunos valores pueden incluir caracteres que son delimitadores de URL conservados (por ejemplo, "&", "=", "'" y "?"). Para asegurarse de que la URL interpreta valores correctamente, debe codificar con URL caracteres no seguros sustituyéndolos por un carácter de % seguido por el valor correspondiente con su equivalente hexadecimal UTF-8. Los delimitadores de URL fuera de los valores de los parámetros deben estar en texto sin formato y no pueden codificarse.

Por ejemplo, el parámetro center a continuación no funcionará correctamente porque hay que codificar dos de los caracteres de la coma:

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100,100,102100,rotation:45

La siguiente es la versión correctamente escrita de la URL anterior:

https://experience.arcgis.com/experience/<AppId>#map_1=center:-100%2C100%2C102100,rotation:45

Parámetros del widget Mapa

Las subsecciones siguientes describen los parámetros URL relacionados con los mapas. Puede utilizar la configuración de Gestionar estado URL para que estos parámetros aparezcan en la URL cuando el usuario interactúe con el widget Mapa. Todos los parámetros del widget Mapa siguen las marcas de almohadilla (#).

Nota:

Los parámetros center, scale y rotation del widget Mapa solo funcionan con mapas web, no con escenas web.

Definir el mapa web o la escena web para cuando se cargue por primera vez un widget de Mapa

Si su widget Mapa contiene varios mapas web o escenas web, puede definir cuál está activo cuando se carga la aplicación mediante active_datasource_id seguido del Id. de la fuente de datos del elemento deseado. A continuación, se muestran algunos ejemplos:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=active_datasource_id:<dataSourceId>

https://experience.arcgis.com/experience/<AppId>#map_1=active_datasource_id:dataSource_4

Centrar un mapa

Para centrar un mapa en una ubicación concreta, utilice center seguido de las coordenadas deseadas y el Id. conocido del sistema de coordenadas deseado (WKID). A continuación, se muestran algunos ejemplos:

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

Definir la escala del mapa

Para definir la escala del mapa, utilice scale seguido de un valor de escala. A continuación, se muestran algunos ejemplos:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=scale:<scaleValue>

https://experience.arcgis.com/experience/<AppId>#map_1=scale:19257701.0800833

Definir la rotación del mapa

Para definir la rotación del mapa, utilice rotation seguido de un número de grados. A continuación, se muestran algunos ejemplos:

https://experience.arcgis.com/experience/<AppId>#<mapWidgetID>=rotation:<rotationValue>

https://experience.arcgis.com/experience/<AppId>#map_1=rotation:45

Definir el punto de visualización del mapa

Para definir el punto de visualización, que es la ubicación o posición de la cámara desde la que ver el mapa o la escena, utilice viewpoint. Si su widget de mapa contiene varios mapas o escenas, el parámetro de punto de visualización afecta a todos ellos.

Los puntos de visualización y sus propiedades suelen escribirse en formato JSON, como en el siguiente ejemplo:

 {
  "rotation": 0,
  "scale": 19966005.903731048,
  "targetGeometry": {
    "spatialReference": {
      "latestWkid": 3857,
      "wkid": 102100
    },
    "x": -9870655.016044471,
    "y": 4724533.527708739
  }
}

Para definir un punto de visualización específico mediante la URL, debe codificar en dicha URL todas esas propiedades escritas normalmente en formato JSON. A continuación, encontrará un ejemplo:

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

Nota:

Los parámetros center, scale y rotation tienen mayor prioridad que el parámetro viewpoint y lo invalidarán si utiliza varios parámetros relacionados con un mapa web.

Nota:

Los cambios de extensión de mapa causados por acciones de mensaje tienen mayor prioridad que los cambios de extensión provocados por parámetros de la URL. Por ejemplo, si intenta abrir un widget Mapa a extensiones predefinidas utilizando los parámetros de URL anteriores, pero el widget Mapa también está configurado como destino del desencadenador Cambios de selección de registros y de las acciones de mensaje Desplazar a o Acercar a, las extensiones asociadas a las acciones de mensaje sustituyen a las extensiones que usted estableció con los parámetros de URL.

Definir la visibilidad de las capas del mapa

Para definir la visibilidad de las capas de un mapa, utilice layer_visibility.

La visibilidad de las capas suele escribirse en formato JSON, como en el siguiente ejemplo:

 {
  "widget_1-dataSource_1": {
    "widget_1-dataSource_1-187938b7328-layer-2": false
  },
  "widget_1-dataSource_4": {
    "widget_1-dataSource_4-18a690b433a-layer-4": false
  }
}

Para que las capas de su mapa estén visibles u ocultas mediante la URL, debe codificar toda la información en la URL después del parámetro layer_visibility. A continuación, encontrará un ejemplo:

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

Parámetros del widget Buscar

Las siguientes subsecciones describen parámetros URL relacionados con la búsqueda. Puede utilizar la configuración de Gestionar estado URL para que estos parámetros aparezcan en la URL cuando el usuario realice una búsqueda. Los parámetros del widget Buscar siguen las marcas de almohadilla (#).

Mostrar la entrada de la búsqueda

El parámetro searchText muestra el texto que el usuario ha introducido para realizar una búsqueda. A continuación, se muestra una URL de ejemplo con el parámetro searchText:

https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%7D

Mostrar el origen de la búsqueda

Cuando el usuario realiza una búsqueda utilizando solo algunos de los orígenes de búsqueda disponibles, en la URL aparece uno de los dos parámetros siguientes:

Si al menos un origen de búsqueda está desmarcado en el menú desplegable del widget en tiempo de ejecución, aparece el parámetro serviceEnabledList y define qué orígenes de búsqueda se van a comprobar. Este parámetro se oculta cuando se comprueban todos los orígenes de búsqueda. A continuación se muestra un ejemplo de URL codificada:
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"serviceEnabledList"%3A%5B"<SourceID1>"%2C"<SourceID2>"%5D%7D
```
Si el usuario hace clic en una sugerencia de búsqueda para aplicar una búsqueda, aparece el parámetro "status":{"configId":"<SourceID>"} y define el origen de búsqueda único que se está utilizando en la búsqueda actual. Tanto la entrada como el origen de la búsqueda aparecen en la URL. A continuación se muestra un ejemplo de URL codificada:
```
https://experience.arcgis.com/experience/<AppId>#<searchWidgetID>=search_status:%7B"searchText"%3A"<text>"%2C"status"%3A%7B"configId"%3A"<SourceID>"%7D%7D
```

Si el usuario hace clic en una sugerencia de búsqueda procedente de un origen localizador, la URL muestra la magicKey asociada a la sugerencia. magicKey es un Id. único que vincula una sugerencia a una dirección o lugar concretos. A continuación se muestra un ejemplo de propiedades y parámetros de búsqueda escritos en formato JSON:

{
	"searchText": "<text>",
	"status":{
		"configId": "<SourceID>",
		"magicKey": "<key>"
	}
}

A continuación se muestra un ejemplo de las mismas propiedades y parámetros anteriores escritos en una URL codificada:

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

Parámetros relacionados con el inicio de sesión

Las siguientes subsecciones describen parámetros de URL relacionados con el inicio de sesión.

Compartir la autenticación mediante un widget Integrar

Algunas aplicaciones web solicitan a los usuarios que inicien sesión con una cuenta de ArcGIS. Una aplicación puede requerir a los usuarios que inicien sesión debido a su configuración de uso compartido, porque la aplicación incluye widgets que utilizan contenido Premium o por otros motivos.

Para integrar una aplicación web de ArcGIS en una aplicación de Experience Builder cuando ambas requieren que los usuarios inicien sesión, puede agregar los parámetros de URL arcgis-auth-origin y arcgis-auth-portal para compartir la autenticación entre las dos aplicaciones de modo que los usuarios solo tengan que iniciar sesión una vez.

Para integrar una aplicación privada Experience Builder en otra aplicación Experience Builder, utilice ?arcgis-auth-origin= para definir la URL del dominio de la aplicación host para la autenticación. A continuación, encontrará un ejemplo:

https://<orgdomain>/experience/<AppID>/?arcgis-auth-origin=<your host app domain, such as https://localhost:3001>

Para integrar una aplicación basada en API JavaScript, como, por ejemplo, una aplicación Web AppBuilder, utilice ?arcgis-auth-origin= para la autenticación del dominio de aplicación host y ?arcgis-auth-portal= para JavaScript para el portal ArcGIS desde el que la aplicación basada en la API de JavaScript necesita autenticación. A continuación, se muestran algunos ejemplos:

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

Enviar usuarios a la página de inicio de sesión de una organización

En general, cuando los usuarios intentan acceder a una aplicación privada de Experience Builder en ArcGIS Online, se les dirige a la página principal de inicio de sesión de ArcGIS Online. Para enviar usuarios a la página de inicio de sesión de su organización, utilice org seguido del nombre abreviado de su organización.

https://experience.arcgis.com/experience/<AppId>/?org=<yourorgshortname>

¿Algún comentario sobre este tema?