Introducing the Survey123 Web App JavaScript API
Updated August 19, 2020. Added link to the API reference documentation
Updated August 6, 2020. Documented mode (edit, view) property. New in 3.10
The Survey123 web app JavaScript API is designed to help you embed, style and interact with Survey123 smart forms within your own web applications. At a glance, here is what you can do with this API and a little bit of JavaScript magic:
- Programmatically embed a Survey123 web form within a web page at run-time.
- Apply a custom css to the embedded web form to make it look fit within your own web app.
- Programmatically read and write values into the embedded web form from your own web application.
- Subscribe to web form events such as onFormLoaded, onFormSubmitted or onValueChanged.
There are many applications for this new API. In the animation below, for example, a form is embedded within a web page used to report the speed of your internet connection. When the page is initially loaded, a big button is shown to help users initiate a quick internet speed test. One the connection speed is estimated, a Survey123 web form is loaded and the output of the speed test is automatically added into the form. At that point, the end user can complete the remaining questions and submit. The whole idea with this is that the logic to measure the internet speed of your connection sits in your web application, but when the time comes to submit data like your location or email contact, a Survey123 form is used for that. Through the Survey123 web app JavaScript API you can make your web app talk to the form and load the measured internet speed right away to make the process simpler.
Thanks to the Applications Prototype Lab for sharing the above example and making its source code available in GitHub!
You may also want to leverage the Web App JavaScript API to bring Survey123 forms into existing websites. Of course, you can always embed your survey by copying and pasting an embed link, but using the Web App API has the advantage that you can make your form interact with the website and vice-versa. For example, say you want to embed in the website of your city a form to capture incidents or issues that need attention. You can pre-populate certain questions in the form using information gathered from your own website. Similarly, you can feed your website with information entered by the user Survey123 while the form is being completed, or when the data is finally sent.
Getting Started (Hello World)
The following is about the simplest code snippet showing the basics of the Survey123 Web App JavaScript API. This sample loads a custom web form into a web page and pre-populates a couple of questions in it.
Lets have a closer look at the code:
- Line 2: In this line we import the Survey123 web app JavaScript API. The address of the latest version of the API is http://survey123.arcgis.com/api/jsapi
- Line 5: Your web form needs a container in your web page. Typically, you will want to use a DIV HTML element. You can control the exact size of the the container in your page, although keep in mind that you cannot make it too small or otherwise your web form will not have room to display.
- Lines 7-14: This is where we create a Survey123WebForm JavaScript object. The constructor requires at least the following attributes:
- clientId: The client ID is a string that proves that you have explicitly authorized the use of Survey123 web app API from your web page. You need to create the Client ID through the https://developers.arcgis.com/ website. Check the Generating a Client ID section later in this article for details.
- container: This is the HTML element in which you want your web form to be displayed. Typically a DIV.
- itemID: This is the ArcGIS itemID of your web form. Check the Getting the ItemID of a web form section later in this article for details.
- token: This attribute is only needed if you are targeting a private survey.
There are a number of optional attributes you can also set. In the example above, we added the defaultQuestionValue attribute to set the default value of a couple of questions. Check the Web Form attributes section later in this document for a complete list.
Generating a Client ID
To authorize the use of the Survey123 web app JavaScript API within your web application, you must provide a valid Client ID. You can create a Client ID through ArcGIS for Developers as follows:
- Login into ArcGIS for Developers and open the Dashboard.
- Create a New Application and switch to the Authentication tab
- Add your web application URL and/or domain to the list of Redirect URIs.
- Copy the Client ID.
Getting the ItemID of a Web Form
ItemIDs uniquely identify ArcGIS items within your organization. You can find more information about itemIDs in the https://community.esri.com/community/gis/web-gis/arcgisonline/blog/2019/06/06/where-can-i-find-the-i... article. To get the ItemID of your web form:
- Login to Survey123.arcgis.com.
- Open the Overview or Design tab of your survey
- The portion in the URL highlighted in the screenshot below is the itemID.
More details (Web Form attributes)
Here is the list of all attributes supported by the Web Form object. The complete reference is at https://developers.arcgis.com/survey123/api-reference/web-app
Property Description
| container | The HTML element that will contain the web form, typically a DIV. |
| clientId | A valid Client ID for your domain registered in ArcGIS for Developers |
| itemId | The ItemId of the web form you want to load. |
| mode | (Optional) Defines if the form will create a new record on submit or update the specified record through the globalid property. Values are 'edit' or 'view'. If this property is not specified the submit button adds a new record. |
| globalId | (Optional) Set this property only if mode='edit' or 'view'. Defines the record that should be loaded in the webform to be edited or viewed. For example: globalId: '72dc4442-773e-4490-88e0-fd7ad5c6d234'. |
| portalUrl | (Optional) The URL of your ArcGIS portal. If left empty, defaults to https://www.arcgis.com |
| token | Required if you work with private surveys. |
| hideElements | (Optional) Elements can be set to be hidden, including navbar, theme, header, subHeader. For example: ["navbar","header","subheader"] You can also hide questions within your survey. For example: For example: ['field:yourQuestionName'] |
| autoRefresh | (Optional) Enable auto refresh the survey after submit successfully. You can set autoRefresh=3 which will refresh the survey after 3 second |
| defaultQuestionValue | (Optional) Lets you populate questions in the form. For example: {field_0: 'value1', field_1: 'value2'} |
| isDisabledSubmitToFeatureService | (Optional) Set this property to true and the web form will not send data to your feature service. |
| onFormLoaded | (Optional) Invokes a callback function when loaded. For example: function({form:Form, contentHeight: number }) |
| onFormResized | (Optional) |
| onFormSubmitted | (Optional) Invokes a callback function when the form is submitted. For example: function({surveyFeatureSet: SurveyFeatureSet}) |
| onQuestionValueChanged | (Optional) Invokes a callback function when values in your form change. For example: function({field: string; value: any; path: string; repeatIndex: number; formId: string}) |
| width | (Optional) Takes a number in pixels. Controls the width of the survey although anything smaller than 660 will be ignored. |
More details (Web Form methods)
Web Form methods allow you to set the value of questions within your form from a JavaScript function. You can also use them to programmatically change the style of your form.
Method Description
| .setQuestionValue | Used to set the value of a question, or questions, at run-time. For example:
webform.setQuestionValue({ |
| .setGeopoint | Used to center the map and set the geopoint value to a given location. For example:
webform.setGeopoint({ x=-117.34, y=43.78 });
It is commonly used in combination with the Geolocation API. |
| .setStyle | Used to apply CSS styling to your web form. For example:
webform.setStyle({ |
Samples
- Hello World: A bare bones sample showing how to embed a web form within a web page.
- Speed Test: A more elaborate sample written by the Esri Geo Experience Center’s Applications Prototype Lab. It integrates a simple routine to estimate internet speed connection and then uses that estimation to pre-populate a question in a web form.
Version locking
In developer samples and throughout the blogs and documentation you will often see that the API is imported using this URL: http://survey123.arcgis.com/api/jsapi This is the home of the API and always returns the latest available version of it (non-version locked).
If you rather lock the version of the API used in your web application to a specific version, all you need to do is to add the version number you want at the end of the URL. For example: http://survey123.arcgis.com/api/jsapi/3.13 will give you access to the 3.13 version specifically.
You may want to consider the use of version-locked imports in your code to avoid surprises when new releases are made available.