Embed a survey using JavaScript

Use JavaScript to embed, style, and interact with a survey in your custom web app.

Configure a survey in ArcGIS Experience Builder

ArcGIS Experience Builder allows you to create web apps and pages using flexible layouts, content, and widgets that interact with 2D and 3D data.

Experience Builder uses the Survey123 web app API so you can add a survey to your web app without writing any code. Use the Survey widget to add a survey. You can configure whether the user creates a survey or selects an existing survey, the appearance of the survey, and where data from the survey is sent.

An example of embedding a survey in a web app using Experience Builder is the US Government Employee Travel Information for France survey.

Embed a survey in a custom web app

You can use JavaScript to embed, style, and interact with a survey directly in your web app.

To do this, create a survey object in your app. You can precalculate answers to questions, listen to events or other parts of the web app, and change or add steps to be completed when the user clicks the Submit button.

Start by importing the Survey123 web app API into your HTML page using the following code:

Use dark colors for code blocksCopy
<script src="https://survey123.arcgis.com/api/jsapi/3.14"></script>

The following code sample shows how to create a web form instance with example clientId and itemId values:

Use dark colors for code blocksCopy

webform = new Survey123WebForm({
    clientId: "TG75Zb6OXqL7jgcQ",
    container: "formDiv",
    itemId: "129132bbedcb490488a162aa996bb693"
});

The following code sample shows how to request your location and pass it to the form:

Use dark colors for code blocksCopy

webform = new Survey123WebForm({
    clientId: "TG75Zb6OXqL7jgcQ",
    container: "formDiv",
    itemId: "129132bbedcb490488a162aa996bb693"
    onFormLoaded: (data) => {
      if(navigator.geolocation){
        navigator.geolocation.getCurrentPosition(position => {
          webform.setGeopoint({
            x: position.coords.longitude,
            y: position.coords.latitude
          });
        }, () => { console.error('Unable to retrieve your location'); });
      } else {console.error('Geolocation is not supported by your browser'); }
    }
});

Parameters

When you embed a survey in either ArcGIS Experience Builder or your custom web app, you can add parameters to control the way survey is displayed.

The following ArcGIS Experience Builder example displays the form for a selected record in edit mode:

Use dark colors for code blocksCopy
https://survey123.arcgis.com/share/acb28b212b5542acbbdbaa35feba0765?mode=edit&globalId={globalid}

Available parameters are listed in the following table:

Parameter	Description	Example	Type
`center`	Centers the map to known latitude, longitude, and optional altitude.	`center=37.8199,-122.4783,20`	String
`field:fieldname`	Populates survey questions with field values.	`field:surname=Klauser`	String
`portalUrl`	Specifies the URL to the portal where the survey item is hosted.	`portalUrl=https://myorg.arcgis.com`	String
`open`	Specifies the app used to open the survey. Valid values are `web` , which opens the survey in the web app (the default), `native` , which opens the survey in the field app if the field app is installed, and `menu` , which opens a web page to determine the app that will open the survey.	`open=web`	String
`hide`	Hides elements of the survey in the web app. The parameter can accept multiple values separated by a comma. Valid values are `navbar` (the bar at the top of the survey, including options to log in, log out, and change language), `header` , `description` , `footer` , `submit` , `theme` , and `leaveDialog` (the warning message displayed when navigating away from or closing the page). You can also use the `field:fieldName` parameter to hide a specific question, group, page, or repeat, by providing the name in place of `fieldName` . Note Questions in repeats cannot be hidden individually.	`hide=header,description,footer,theme`	String
`locale`	Switches the language of the survey. It only works if the survey includes multiple languages.	`locale=zh-cn`	String
`mode`	Sets the mode of the web app. Valid values are `edit` , which sets the survey to edit an existing entry rather than create one; `view` , which opens an existing entry in read-only mode; and `copy` , which creates a survey that is populated with the contents of the specified entry. When using this parameter, the `globalId` parameter must also be provided.	`mode=edit&globalId=42db492cb06111ea...`	String
`globalId`	Specifies the survey record that's loaded into the form. Valid values are the global IDs for existing survey records. The name of this parameter is case sensitive.	`globalId=42db492cb06111ea...`	String
`recalculate`	Can only be used with `mode=edit` . Forces specified questions to be recalculated as the survey is loaded, without use of the Recalculate button.	`recalculate=field:question1,field:question2`	String
`version`	Sets the version of the web app that will be used. The only valid value is `latest` , which uses the latest version of the web app, even if the survey is version locked.	`version=latest`	String
`token`	Passes a valid token for a survey. It can be used to allow respondents to respond to a survey that requires an ArcGIS account to access it without signing in.	`token= E60M4Gsc-h4Q8plqQ...`	String
`autoRefresh`	Refreshes the survey after submission. Specify the delay (in seconds) before the survey is refreshed.	`autoRefresh=3`	Integer
`encodeUrlParams`	Obscures URL parameters. The resulting URL will instead include a `code` parameter representing all encoded parameters; parameters included outside of this `code` parameter will be ignored.	`encodeUrlParams=true`	Boolean
`width`	Sets the width for the survey, in pixels. This also affects other controls within the survey, such as text boxes.	`width=1000`	Integer

Web app API reference

For a complete list of JavaScript properties and methods, see the Survey123 web app API reference.

Survey123Guide

Embed a survey using JavaScript

Was this page helpful?

Was this page helpful?