Hidden Fields (API)

This option allows you to pipe text from ‘Hidden Fields’ using a QueryString or JavaScript API.

These terms simply refer to the way of creating applications that access the features or data of other digital services. You would be using this component to retrieve relevant data on your respondents, from a source external to this site.

Step One: Defining your Data

Before you can incorporate this type of Text Piping, you will need to define what kind of data you want ‘passed in’ to your project. To do this you will need to insert the External Datasource (hidden questions) element, which you’ll find under the “Special” category in the Question Library. Once added, it’s labelled “Hidden Fields” in your question list.

Then input the names of your fields, and all data will be stored as a string.

Note: Field name must contain no spaces, and only ‘**-**‘ or ‘**_**’ as special characters.

Step Two: Passing the data in

There are two ways to ‘pass data in’ to your survey from an external source. The first of these is by using Querystring parameters, whilst the second employs the JavaScript API.

Querystring Parameters

This method requires you to have used the hyperlink launch option. For the data to be unique to each respondent, you would have to generate the link server side.

Below you will see an example of a standard survey link, without the Querystring parameters applied.

https://shout.com/s/**__**5urV3yc0de

Add your parameter names to the querystring exactly as you entered them as field names in Step One — no prefix is needed. See the example below, for fields named name and email:

https://shout.com/s/5urV3yc0de**?name=Jeff&email=luke@example.com**

As you can see above, the fields included in this Querystring are:

• name=Jeff
• email=luke@example.com

The first half of each parameter (everything before the “**=**”) must exactly match a field name entered in Step One, whilst the second half provides the corresponding information.

JavaScript API

This method allows you to embed your project directly into your website. It’s a great alternative when standard embed button codes or placeholder codes do not fully suit your requirements.

Note: You will need a basic understanding of JavaScript to use this method.

Simply add a property called “custom” to the config object, this may contain a single level object of strings. Example below:

{ formId: "###", custom: { userId: "32453", firstName: "Luke", lastName: "Smith", email: "luke@shout.com" } }

For more information on how to employ JavaScript API, please refer to this article.

Step Three: Using the data in the live survey (optional)

The data stored by either of the above methods can be used in your live survey, through the ‘Hidden Fields’ element discussed in Step One.

Step Four: Passing the data out in a redirect URL (optional)

You can pass information back to your website for confirmation that a respondent has completed your survey/project. To do this, select your Exit Page in the project builder. You will see three options:

• Standard (with advertising)
• Design Custom Page
• Redirect to Web Address

Select the ‘Redirect to Web Address’ option, and enter the URL of the site you wish respondents to be directed to in the space provided.

Below is an example of how you can customize this URL with a unique code, so your website records respondents being redirected.

https://mywebsite[dot]com/confirmationpage?email=[email]

The [email] section will be replaced with the input email address from the QueryString parameters or JavaScript API call you passed earlier.