Integrar con otras aplicaciones

ArcGIS Survey123 se puede integrar con otras aplicaciones utilizando vínculos a la aplicación web o aplicación de campo Survey123. Los vínculos a la aplicación web comienzan por https://survey123.arcgis.com/share. Los vínculos a la aplicación de campo pueden ser un vínculo Survey123 o un vínculo de esquema de URL personalizado.

Los vínculos de Survey123 comienzan con https://survey123.arcgis.app y funcionan solo en iOS y Android. Los vínculos de Survey123 cumplen los requisitos establecidos por App Store y Google Play, permiten la vinculación a más aplicaciones y admiten vínculos abreviados que son más sencillos de compartir.

Los vínculos de esquema de URL personalizado comienzan por arcgis-survey123:// y funcionan en Windows, Android y con un grupo seleccionado de aplicaciones de iOS. Los vínculos de esquema de URL personalizado no se pueden acortar y puede ser difícil abrirlos en Android. Plantéese presentar vínculos de esquema de URL personalizados en forma de hipervínculos, de forma similar a lo siguiente:

<a href="arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19">Open survey</a>

Antes de usar un vínculo que contenga parámetros para iniciar una encuesta en la aplicación de campo, es recomendable que la aplicación ya esté instalada en el dispositivo. Para obtener más información, consulte Instalar la aplicación de campo Survey123.

Parámetros para una aplicación de campo

Los siguientes parámetros se pueden usar para personalizar cómo se abre una aplicación de campo:

Parámetro	Descripción	Ejemplo	Tipo
center	Centra el mapa en una latitud, longitud y altitud opcional conocidas.	center=37.8199,-122.4783,20	Cadena de caracteres
field:fieldname	Rellena las preguntas de la encuesta con valores de campo.	field:surname=Klauser	Cadena de caracteres
portalUrl	Especifica la dirección URL del portal donde está alojado el elemento de la encuesta.	portalUrl=https://myorg.arcgis.com	Cadena de caracteres
itemID	Especifica el formulario que se debe abrir.	itemID=36ff9e8c13e042a58cfce4ad87f55d19	UUID
download	Descarga automáticamente la encuesta cuando el dispositivo está en línea. El valor predeterminado es true.	download=false	Booleano
action	Especifica cómo se abre la encuesta. Los valores admitidos son: collect (el predeterminado), edit, view y copy.	action=edit	Cadena de caracteres
folder	Especifica la carpeta en la que se buscará cuando se use el parámetro filter. Los valores admitidos son inbox, drafts, outbox, sent y * (todas las carpetas).	folder=drafts	Cadena de caracteres
callback	Especifica la dirección URL a la que volver cuando se completa una acción de formulario (por ejemplo, enviar, mover a borradores, cancelar o salir).	callback=https://quickcapture.arcgis.app	Dirección URL
callback:status	Especifica el estado de la encuesta cuando se activa la devolución de llamada. Los valores admitidos para el estado son cancel, draft, submit y close. El estado close solo se puede usar al action=view.	callback:draft=https://quickcapture.arcgis.app	Cadena de caracteres
filter	Busca una cadena de caracteres específica en encuestas existentes en el dispositivo. Proporcione el nombre de un campo en particular para buscar solo en ese campo la cadena de caracteres deseada.	filter=Klauser	Cadena de caracteres
update	Actualiza la Bandeja de entrada e intenta enviar encuestas a la Bandeja de salida. El valor predeterminado es false.	update=false	Booleano
q:queryparameter	Consulta la capa de entidades para buscar un registro existente. Se puede utilizar para recuperar contenido que no está en el dispositivo.	q:where=ws_stationnumber=5171 q:where=waterbodytype='Lake' q:globalId=1d392670-33e2-456d-8435-7fad3abd8bb9	Cadena de caracteres

Parámetros para una aplicación web

Los siguientes parámetros se pueden usar para personalizar cómo se abre una aplicación web:

Parámetro	Descripción	Ejemplo	Tipo
center	Centra el mapa en una latitud, longitud y altitud opcional conocidas.	center=37.8199,-122.4783,20	Cadena de caracteres
field:fieldname	Rellena las preguntas de la encuesta con valores de campo.	field:surname=Klauser	Cadena de caracteres
portalUrl	Especifica la dirección URL del portal donde está alojado el elemento de la encuesta.	portalUrl=https://myorg.arcgis.com	Cadena de caracteres
open	Especifica qué aplicación se utiliza para abrir la encuesta. Los valores válidos son web, que abre la encuesta en la aplicación web (el valor predeterminado), native, que abre la encuesta en la aplicación de campo si la aplicación de campo está instalada y menu, que abre una página web para determinar la aplicación que abrirá la encuesta.	open=web	Cadena de caracteres
hide	Oculta los elementos de la encuesta en la aplicación web. Este parámetro puede aceptar varios valores separados por comas. Los valores válidos son navbar (la barra en la parte superior de la encuesta con opciones para iniciar sesión, cerrar sesión y cambiar de idioma), header, description, footer, submit, theme y leaveDialog (el mensaje de advertencia mostrado al cambiar de página o cerrarla). También puede utilizar el parámetro field:fieldName para ocultar una pregunta, grupo, página o repetición en concreto, indicando su nombre en lugar de fieldName. Nota: No es posible ocultar de manera individual las preguntas de repeticiones.	hide=header,description,footer,theme	Cadena de caracteres
locale	Cambia el idioma de la encuesta. Solo funciona si la encuesta incluye varios idiomas.	locale=zh-cn	Cadena de caracteres
mode	Define el modo de la aplicación web. Los valores válidos son: edit, que configura la encuesta para editar una entrada existente en lugar de crear una; view, que abre una entrada existente en modo de solo lectura; y copy, que crea una encuesta que se rellena con el contenido de la entrada especificada. Al utilizar este parámetro, también se debe proporcionar el parámetro globalId.	mode=edit&globalId=42db492cb06111ea...	Cadena de caracteres
globalId	Especifica el registro de la encuesta cargado en el formulario. Los valores válidos son los Id. globales de los registros existentes de la encuesta. El nombre de este parámetro distingue entre mayúsculas y minúsculas.	globalId=42db492cb06111ea...	Cadena de caracteres
recalculate	Solo se puede utilizar con mode=edit. Obliga a recalcular las preguntas especificadas cuando se carga la encuesta, sin utilizar el botón Recalcular.	recalculate=field:question1,field:question2	Cadena de caracteres
version	Establece la versión de la aplicación web que se utilizará. El único valor válido es latest, que utiliza la última versión de la aplicación web, incluso si la encuesta tiene la versión bloqueada.	version=latest	Cadena de caracteres
token	Envía un token válido para una encuesta. Se puede utilizar para que los encuestados que responden a una encuesta que requiere una cuenta de ArcGIS accedan sin tener que iniciar sesión.	token= E60M4Gsc-h4Q8plqQ...	Cadena de caracteres
autoReload	Vuelve a cargar la encuesta después del envío. Especifique el retraso (en segundos) antes de volver a cargar la encuesta. Anteriormente denominado autoRefresh. El parámetro autoRefresh se admite para la compatibilidad con versiones anteriores.	autoReload=3	Entero
encodeUrlParams	Oculta los parámetros de la dirección URL. En su lugar, la dirección URL resultante incluirá un parámetro code que representa todos los parámetros codificados; los parámetros incluidos fuera de este parámetro code se ignorarán.	encodeUrlParams=true	Booleano
width	Define el ancho de la encuesta, en píxeles. También afecta a otros controles de la encuesta, como los cuadros de texto.	width=1000	Entero

Nota:

El parámetro field:fieldname admite preguntas geopoint, geotrace y geoshape en la aplicación web. En las preguntas geopoint, especifique la latitud, la longitud y la altitud (opcional) separados por espacios. Para geotrace y geoshape, especifique la latitud y longitud de cada vértice separadas por un espacio, con cada par de coordenadas separadas por un punto y coma. Este ejemplo funcionaría para una pregunta geoshape:

field:geoshape=-37.842156723211474 144.95942945338243;-37.83554486071995 144.9726235713864;-37.85681405373047 144.98240735651922;-37.85954045531896 144.97715349053766

Vincular con Survey123 desde un navegador web de escritorio

Puede crear un vínculo para abrir la aplicación de campo e integrarla en otra aplicación. El mismo vínculo se puede introducir también en un navegador web para realizar pruebas.

Nota:

Una vez creado el vínculo, puede reemplazar arcgis-survey123:// por https://survey123.arcgis.app como vínculo de Survey123 para utilizarlo en iOS o Android.

En los siguientes pasos se describe cómo crear un esquema de URL personalizado y utilizarlo en un navegador web de escritorio:

1. Escriba arcgis-survey123:// en el navegador.
   Se abre la aplicación de campo Survey123 (o se le pide que la abra).

   Nota:

   Para iniciar y descargar una encuesta de un portal específico, incluya el parámetro de URL del portal, por ejemplo, arcgis-survey123://?portalUrl=host.domain.com/webadaptor (donde host, domain y webadaptor se reemplazan por su información del portal).

También puede agregar una referencia única a una encuesta y agregarla a la dirección URL. En primer lugar, identifique el Id. de elemento de la encuesta que desea abrir. Es la cadena de caracteres que ArcGIS Online utiliza para identificar exclusivamente su encuesta y se puede encontrar en la URL del elemento de formulario en ArcGIS Online. Por ejemplo, si la dirección URL de la encuesta es https://exampleurl.maps.arcgis.com/home/item.html?id=36ff9e8c13e042a58cfce4ad87f55d19, el Id. de elemento del formulario es 36ff9e8c13e042a58cfce4ad87f55d19.

2. Para incluir la encuesta en la dirección URL que se está creando, agregue ?itemID= y el Id. de elemento del formulario a la dirección URL.
   La dirección URL tendrá un aspecto similar al siguiente:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19

   Si prueba su dirección URL, ahora debería abrir la aplicación de campo Survey123 y abrir inmediatamente la encuesta.

   Nota:

   Si todavía no está en su dispositivo, la encuesta se descarga en él.

Si lo desea, incluya respuestas predeterminadas para las preguntas.
3. Incluya una referencia al campo utilizando el nombre que se le asignó en XLSForm (no su etiqueta) en su URL. Por ejemplo, para rellenar el campo Surname, escriba &field:Surname= y el valor.

   & actúa como separador de parámetro y field: hace referencia al nombre de la pregunta que se va a rellenar.

   La dirección URL tendrá un aspecto similar al siguiente:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

   Ya puede utilizar la URL para abrir la aplicación de campo Survey123 y la encuesta, así como rellenar la pregunta indicada con la respuesta que defina. Puede rellenar varias preguntas en la dirección URL de una encuesta. En los nombres de campo se distingue entre mayúsculas y minúsculas.

Si lo desea, agregue coordenadas a la dirección URL y defina así una ubicación para una pregunta geopoint en la encuesta.
4. Escriba &center= e introduzca las coordenadas. Escriba las coordenadas de latitud y longitud en grados decimales, separadas por una única coma. Si lo desea, agregue la altitud en metros decimales como tercer valor, también separado por una sola coma.

   La dirección URL tendrá un aspecto similar al siguiente:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

   Esta dirección URL abrirá ahora la aplicación de campo Survey123 y la encuesta elegida, rellenará una pregunta de texto y proporcionará una nueva ubicación predeterminada para su pregunta geopoint.

El contenido de los campos también se puede entregar a Survey123 desde un elemento emergente de un mapa web de ArcGIS, lo que permite la integración con todas las aplicaciones de Esri que utilicen elementos emergentes en un mapa web. Esta funcionalidad puede usarse para rellenar un campo en Survey123 con el contenido de un atributo de entidad, en lugar de un valor establecido, indicando para ello el nombre del atributo entre llaves.
5. Seleccione Configurar ventana emergente para una capa existente de su mapa web. En el menú desplegable de visualización, seleccione Una visualización personalizada de atributos y haga clic en Configurar para insertar un vínculo a su encuesta.

   

   Esta URL rellenaría el campo surname con el contenido del atributo name de la entidad seleccionada, en lugar de con un valor establecido:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname={name}

   Esta URL rellenaría el campo hydrantGlobalID con el Id. global del hidrante seleccionado:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:hydrantGlobalID={globalid}

Nota:

De forma predeterminada, los valores solo se pueden pasar para seleccionar preguntas de selección única o selección múltiple de un elemento emergente en un mapa web si el nombre y la etiqueta de la opción correspondiente son idénticos. Si los nombres y las etiquetas de la lista de opciones son diferentes, puede utilizar las funciones DomainCode o UrlEncode en una expresión ArcGIS Arcade en el elemento emergente para pasar el valor deseado.

No es posible rellenar las preguntas de repeticiones.

Vincular con Survey123 desde otra aplicación

Puede crear un vínculo para utilizarlo en aplicaciones de ArcGIS para abrir Survey123 y capturar una encuesta. En los siguientes pasos se describe cómo crear un vínculo de Survey123 y utilizarlo en un elemento emergente de un mapa web. Este vínculo se introduce en la ventana emergente de un mapa web de su organización de ArcGIS. Puede probar este vínculo con un navegador web (usando pasos similares a los de la sección anterior) en un dispositivo iOS o Android.

1. Seleccione Configurar ventana emergente para una capa existente en un mapa web que se visualizará en el dispositivo.
2. En el menú desplegable de visualización, seleccione Una visualización personalizada de atributos y haga clic en Configurar para insertar un vínculo a su proyecto.
3. En URL, escriba https://survey123.arcgis.app y, en Texto de vínculo, escriba Iniciar Survey123. Haga clic en Aceptar.
   1. Abra su mapa web en un dispositivo móvil desde un navegador o una aplicación de ArcGIS.
   2. Seleccione una entidad y haga clic en el vínculo Iniciar Survey123 de la ventana emergente para abrir Survey123.
4. Para incluir la encuesta en la dirección URL que se está creando, agregue ?itemID= y el Id. de elemento del formulario a la dirección URL.
   La dirección URL tendrá un aspecto similar al siguiente:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19

   Si prueba su dirección URL, ahora debería abrir la aplicación de campo Survey123 y abrir inmediatamente la encuesta.

   Nota:

   Si todavía no está en su dispositivo, la encuesta se descarga en él.

Si lo desea, puede incluir respuestas predeterminadas para las preguntas.
5. Incluya una referencia al campo utilizando el nombre que se le asignó en XLSForm (no su etiqueta) en su URL. Por ejemplo, para rellenar el campo Surname, escriba &field:Surname= y el valor.

   & actúa como separador de parámetro y field: hace referencia al nombre de la pregunta que se va a rellenar.

   La dirección URL tendrá un aspecto similar al siguiente:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

   Ya puede utilizar la URL para abrir la aplicación de campo Survey123 y la encuesta, así como rellenar la pregunta indicada con la respuesta que defina. Puede rellenar varias preguntas en la dirección URL de una encuesta. En los nombres de campo se distingue entre mayúsculas y minúsculas.

Si lo desea, puede agregar coordenadas a la dirección URL y definir así una ubicación para una pregunta geopoint en la encuesta.
6. Escriba &center= e introduzca las coordenadas. Escriba las coordenadas de latitud y longitud en grados decimales, separadas por una única coma. Si lo desea, agregue la altitud en metros decimales como tercer valor, también separado por una sola coma.

   La dirección URL final tendrá un aspecto similar al siguiente:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

   Esta dirección URL completa ahora abre la aplicación de campo Survey123 y la encuesta elegida, rellena una pregunta de texto y proporciona una nueva ubicación predeterminada para su pregunta geopoint.

Entregar parámetros a la aplicación web Survey123

La aplicación web Survey123 acepta parámetros con el mismo formato que la aplicación de campo. La única diferencia es que debe usar un signo de interrogación para separar el Id. de elemento de la encuesta del primer parámetro, en lugar de usar un ampersand (los ampersands se siguen usando para separar los parámetros). La siguiente URL de ejemplo entrega los parámetros de apellidos y coordenadas a una encuesta en la aplicación web Survey123:

https://survey123.arcgis.com/share/36ff9e8c13e042a58cfce4ad87f55d19?field:surname=Klauser&center=37.8199,-122.4783

La aplicación web Survey123 también admite distintos parámetros que la aplicación de campo Survey123 no admite. Estos parámetros están relacionados con la presentación de la encuesta en un navegador.

Nota:

Si un valor de parámetro incluye espacios, signos más (+) u otros caracteres especiales, estos caracteres deben estar codificados por porcentaje. Para obtener más información, consulte Codificar parámetros de URL.

Entregar parámetros a Survey123 Connect

El esquema de URL utilizado por Survey123 Connect es arcgis-survey123connect://, que permite al usuario descargar y abrir automáticamente una encuesta, ya lista para su edición.

El esquema de URL admite parámetros distintos de la aplicación de campo o aplicación web; acepta el Id. de elemento del formulario y la URL del portal en el que está almacenado el elemento. La siguiente URL de ejemplo abre una encuesta concreta en Survey123 Connect desde el portal de ArcGIS Enterprise proporcionado, y la descarga si aún no está presente:

arcgis-survey123connect://?portalUrl=https://exampleportal.esri.com/arcgis&itemID=36ff9e8c13e042a58cfce4ad87f55d19

Aunque guarde su encuesta en ArcGIS Online, debe indicar la URL del portal de ArcGIS Online, como esta:

arcgis-survey123connect://?portalUrl=https://www.arcgis.com&itemID=36ff9e8c13e042a58cfce4ad87f55d19

Nota:

Estos parámetros de URL solamente se pueden utilizar para abrir formularios de su propiedad. No puede utilizarlos para abrir encuestas a las que tiene acceso, pero que no creó.

Vincular a otras aplicaciones desde Survey123

Es posible abrir varias aplicaciones mediante vínculos. Puede crear una dirección URL que abra otra aplicación y la inserte en su encuesta. Estas aplicaciones también pueden aceptar parámetros personalizados en sus direcciones URL, de la misma forma que Survey123.

Para empezar, debe agregar a la encuesta una pregunta de tipo nota con una etiqueta que contenga la dirección URL.

Nota:

En dispositivos iOS, los esquemas de URL que no sean HTTP y HTTPS deben agregarse a una lista de esquemas aprobados dentro de la aplicación. Los siguientes esquemas de URL están aprobados en Survey123:

• arcgis-appstudio-player
• arcgis-quickcapture
• arcgis-collector ArcGIS Collector solo en Windows
• arcgis-trek2there
• arcgis-navigator
• arcgis-workforce Workforce for ArcGIS (Classic) solamente
• comgooglemaps
• foreflightmobile
• waze
• spike-partner

Para vincular a Field Maps y las versiones más recientes de Workforce, debe utilizar un vínculo de aplicación que comience por HTTP o HTTPS.

Consulte la información que aparece a continuación sobre algunas de las aplicaciones de Esri habituales que se pueden abrir mediante Survey123:

• ArcGIS QuickCapture
• ArcGIS Field Maps
• ArcGIS Navigator

Codificar parámetros de URL

Aunque los parámetros de URL que no están codificados funcionan en algunos entornos, se recomienda codificar los parámetros de URL. La codificación sustituye caracteres no válidos por el signo de porcentaje, %, seguido de su equivalente hexadecimal.

Por ejemplo, a continuación, se muestra un vínculo de Survey123 que utiliza una devolución de llamada para volver a un proyecto específico en QuickCapture con parámetros que no están codificados:

https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&callback=https://quickcapture.arcgis.app?itemID=867895a71a1840399476fc717e76bb43

La siguiente es la misma URL con parámetros codificados:

https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&callback=https%3A%2F%2Fquickcapture.arcgis.app%3FitemID=867895a71a1840399476fc717e76bb43

Un signo igual que especifica un corte entre una clave y su valor no se debe codificar.

Una forma de crear parámetros codificados es utilizar ArcGIS Arcade. La función UrlEncode le permite definir un conjunto de pares de valores clave que representan cada parámetro y producen una dirección URL con la codificación adecuada.

Es posible que el autor de una encuesta también desee ocultar los parámetros de la URL para que los datos confidenciales no estén visibles en la URL. En este caso, al crear una URL para utilizarla en la aplicación web, incluya encodeUrlParams=true. Para obtener más información, consulte Parámetros para una aplicación web.