Zu Hauptinhalten wechseln

FV Decipher Unterstützung

Alle Themen, Ressourcen für FV Decipher benötigt.

 
decipher

Configuring Sample Sources

1:  Overview

Sample sources determine how respondents got to the survey and where they are directed at survey completion.

Sample sources can be configured in the XML Editor to meet the needs of the current project the necessary name, URL variables, error messages, and exit pages.

2:  Adding Sample Sources

Sample sources are defined within the XML using the <samplesources> and <samplesource> tags. For example, in the code below, there are two individual <samplesource>’s nested within the parent <samplesource> tag. The list variable is used to differentiate between the two Sample Sources and the title will display in the reports. Each sample source generates its own survey link that respondents from each source of sample will use to enter the survey.

The code below shows the minimum setup required to create two sample sources:

<samplesources>
 <samplesource list="1" title="EZ-Sample">
 </samplesource>
 <samplesource list="2" title="Sample Co.">
 </samplesource>
</samplesources>

Additional sample sources can be included in a project by nesting another <samplesource> tag under the <samplesources> parent. Each sample source must have a unique list value. For example, a third sample source, Open Sample, is added in the example below, with a list value of "99".

<samplesources>
 <samplesource list="1" title="EZ-Sample">
 </samplesource>
 <samplesource list="2" title="Sample Co.">
 </samplesource>
 <samplesource list="99" title="Open Sample">
 </samplesource></samplesources>

3:   Configuring Sample Sources

Sample sources can be configured to meet the specific needs of a project. The sections that follow will cover the modifications that can be made to the parent <samplesources> and individual <samplesource> tags.

3.1: Default Sample Source

If respondents enters a survey without a list value, they will be defaulted to the sample source in the first programmed order. A default sample source can be declared in the parent <samplesources> tag by adding the default attribute and setting it equal to the list value of the sample source you want to be set as the default. With a default sample source defined, respondents without a list value will be assigned to the defined sample source.

<samplesources default="2">
 <samplesource list="1" title="EZ-Sample">
 </samplesource>
 <samplesource list="2" title="Sample Co.">
 </samplesource>
 <samplesource list="99" title="Open Sample">
</samplesource></samplesources>

In the example above, "Sample Co." is the default sample source. Before the default attribute was added, respondents without a list value would default to "EZ-Sample" because it is in the first programmed order.

3.2: Disable Browser Dupes

Respondents can be prevented from taking a survey multiple times by adding the broswerDupes attribute to the <survey> tag. This change will global and apply to the entire project.

Learn More: Attributes for Field Settings

When enabled, specific sample sources can have this option disabled for that particular sample source by adding the disableBrowserDupes="1". Doing so will override the browswerDupes setting specified in the <survey> tag and allow respondents to take the survey multiple times.

 <samplesource list="99" title="Open Sample" disableBrowserDupes="1">
 </samplesource>

In the example above, the Open Sample includes the disableBrowserDupes="1" attribute allowing respondents entering through that sample source to take the survey more than once.

3.3: URL Variables

In addition to the variables specified in the comma-separated list located in the extraVariables attribute in the <survey> tag, you may provide variables for each <samplesource> individually. Variables can be included in the <samplesource> element to identify unique respondents, signal to sample companies when a respondent completes, supplement survey logic, or establish quota limitations for particular samples.

Variables can be added to a sample source by nesting the <var/> tag under the <samplesource> tag, as shown below. The <var/> tag is self-closing and requires a name attribute which will be appended to the Survey URL.

<samplesource list="1" title="EZ-Sample">
    <var name="referer" />
</samplesource>
<samplesource list="2" title="Sample Co.">
    <var name="seg" /><var name="id" />
</samplesource>

In the example above, the "referer" variable was added to "EZ-Sample" and the "seg" and "id" variables were added to "Sample Co.".

3.3.1: Optional Variables

By default, any variable added to a sample source will be optional. An optional variable does not have to be included in the survey link for a respondent to enter and take the survey. If the variable is present, it will be captured and included in the survey data.

3.3.2: Required Variables

Variables can be made required by adding required="1" to the <var/> tag. A required variable must be present in the survey link in order for a respondent to enter and take the survey.

A value list can be defined to authenticate a required variable by adding the values attribute in addition to required="1". With a value list defined, only respondent with those values defined for the variable will be permitted to take the survey. 

<samplesource list="2" title="Sample Co.">
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" />
 </samplesource>

In the example above, the "seg" variable was made required in the "Sample Co." sample source. Additionally, only values of 1, 2, 3, or 4 will be permitted for the "seg" variable.

3.3.3: Unique Variables

Variables can be made unique by adding unique="1" to the <var/> tag. A unique variable must be present in the survey link in order for a respondent to enter and take the survey. Additionally a respondent cannot use the same value for a unique variable that has already completed the survey or is in progress.

A file can be uploaded to authenticate a unique variable. The file must contain a list of valid values for the unique variable in a single column and be uploaded to the project’s System Files. The filename attribute can then be added in addition to unique="1" and set equal to the uploaded filename.

Learn More: Upload System Files

With a file authentication, only respondents with those values defined in the file will be permitted to take the survey. 

<samplesource list="2" title="Sample Co.">
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" unique="1" filename="ids.dat"/>
</samplesource>

In the example above, the "id" variable was made unique and the "ids.dat" file was uploaded and referenced for authentication.

3.3.4: Utilizing Variables in a Survey

You can pipe a sample source variable into a survey using the following syntax: [url varName] where varName is the name of the sample source variable.


Additionally, logic conditions can be applied based on sample source variables. In the example below, the comment will only display to those respondents that enter the survey with a value of 2 for the seg variable. 

<html label="cm1" cond="seg=='2'">You are in segment 2!</html>

3.4: Error Messages

Error messages related to the sample source variables or respondent location can be modified to the specific needs of a project.

In addition to the messages below, the following error messages related to sample sources and survey links may be displayed.

  • SE-01: Missing list
  • SE-02: Invalid list '[list]'
  • SE-03: Missing required variable [varname] for list=[list]
  • SE-04: Unique variable [varname] already completed for list=[list]
  • SE-05: Variable [varname] has invalid value for list=[list]
  • SE-06: Variable [varname] with value [value] already in progress for list=[list]

Learn More: System Language Resources

3.4.1: Variable Not Provided

If a variable that is required or unique is not passed along with the respondent in the survey link, they will see the following message:

The URL above does not include the proper information to be included in this survey. Please review your invite email for the proper URL, and contact the individual specified if problems persist.

You can override this error message using a resource tag, as shown below:

 <res label="sys_invited.not">Please double check your URL!</res>

Using a resource tag will apply this message to all sample sources. To apply a similar change to a specific sample source, an <invalid> tag can be nested under the corresponding <samplesource> tag with the desired error message.

<samplesource list="2" title="Sample Co.">
    <invalid>Please double check your URL!</invalid>
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" unique="1" filename="ids.dat"/>
</samplesource>


In the example above, the phrase "Please double check your URL!" will be used for any respondent entering the survey with invalid survey link only for the "Sample Co." sample source

3.4.2:  Variable Already In Use

If a variable is already in use, they will see the following error message:

Our records show that you are already taking this survey. If that's not correct, please wait 15 minutes and refresh this page. Thank you.

You can override this message using a resource tag:

<res label="sys_invited.inprogress">Variable already in use!</res>

Using a resource tag will apply this message to all sample sources. To apply a similar change to a specific sample source, an <inuse> tag can be nested under the corresponding <samplesource> tag with the desired error message.

<samplesource list="2" title="Sample Co.">
    <invalid>Please double check your URL!</invalid>
    <inuse>You're already taking this survey!</inuse>
    <var name="seg" required="1" values="1,2,3,4" /><var name="id" unique="1" filename="ids.dat"/>
</samplesource>

3.4.3:  Variable Already Completed

If the variable has already been marked as having completed the survey, they will see the following error message:

Thank you for your interest but it seems you have already finished this survey.

You can override this message using a resource tag:

<res label="sys_invited.used">You've already completed...</res>

Using a resource tag will apply this message to all sample sources. To apply a similar change to a specific sample source, an <inuse> tag can be nested under the corresponding <samplesource> tag with the desired error message.

<samplesource list="2" title="Sample Co.">
    <invalid>Please double check your URL!</invalid>
    <inuse>You're already taking this survey!</inuse>
    <completed>You’re already done here...</completed>
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" unique="1" filename="ids.dat"/>
</samplesource>

3.4.4:  Geographic Requirements Not Met

If the respondent does not meet the geographical requirements for the survey, they will see the following error message:

We're sorry, but this survey has a geographic requirement. You appear to be accessing this survey from outside of that geographic area.

You can override this message using a resource tag:

<res label="sys_invited.geoip">You need to move to take this survey.</res>

Learn more about the geographic requirements: Digital Fingerprinting System

3.5:  Exit Pages

Exit page can be configured to display a message to respondents after they've completed the survey or to redirect them to a website (e.g. the sample provider's website). The <exit> tag is used to define the exit pages.

Exit pages can be shown conditionally by adding a cond to an exit tag. Use cond="qualified", "terminated", or "overquota" to base conditional exit pages on respondent status. Compound logic can be applied to specify unique exit pages for respondents that fulfill certain conditions.

3.5.1 Exit Messages

An exit message can be displayed to respondents by specifying the message between an <exit> tag.

<samplesources default="2">
 <samplesource list="1" title="EZ-Sample">
    <exit cond="qualified">Thank for completing the survey!</exit>
    <exit cond="terminated and s2.val lt 18">Try again when you’re a few years older.</exit>
    <exit cond="terminated">Thank you, but we are looking for someone a little different.</exit>
    <exit cond="overquota">Thank you, but we’re a little full right now.</exit>
    <var name="referer" />
 </samplesource>
 <samplesource list="99" title="Open Sample" disableBrowserDupes="1">
    <exit cond="1">Thank you for your time!</exit>
        </samplesource>
</samplesources>

In the example above, all respondents in the "Open Sample" will see the same message. In the "EZ-Sample" specific exit messages are displayed for respondents based on their status. Additionally, a custom message will display to respondents who terminate because they are under 18 years old.

The system will always apply the first exit condition met by a respondent. If you have more than one qualified, terminate, or overquota condition in your survey, be sure to include your custom condition(s) above the default exit condition for that status (e.g., <exit cond="terminated and q1.r2"> should come before <exit cond="terminated"> in the code).

3.5.2:  Redirecting Links

A redirect link can be specified to send respondents to a desired website by adding the url attribute to the <exit> tag. Sample source variables can be passed back to the redirect link using the following syntax: ${varName} where varName is the variable name.

<samplesource list="2" title="Sample Co.">
    <invalid>Please double check your URL!</invalid>
    <inuse>You're already taking this survey!</inuse>
    <completed>You’re already done here...</completed>
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" unique="1" filename="ids.dat"/>
    <exit cond="qualified" url="http://sampleco.domain.com/survey?stat=q&amp;seg=${seg}&amp;id=${id}"/>
    <exit cond="terminated" url="http://sampleco.domain.com/survey?stat=t&amp;seg=${seg}&amp;id=${id}"/>
    <exit cond="overquota" url="http://sampleco.domain.com/survey?stat=o&amp;seg=${seg}&amp;id=${id}"/> 
</samplesource>

In the example above, a redirect link to the sample provider website is specified for qualified, terminated, and overquota respondents. Additionally, the seg and id variables are passed back through the redirect link so the sample provider can track respondent’s statuses.

3.5.2.1 Redirect After a Timed Delay

Respondent’s can be redirected to a website after specified amount of time by including the timeout attribute in the <exit> tag along with the url attribute and a message to display before redirecting the respondent. The timeout attribute is set equal to the length of the delay in seconds.

<samplesources default="2">
 <samplesource list="1" title="EZ-Sample">
    <exit cond="qualified" url="http://focusvision.com" timeout="3">Thanks again for completing the survey!</exit>
    <exit cond="terminated and s2.val lt 18" url="http://focusvision.com" timeout="3">Try again when you’re a few years older.</exit>
    <exit cond="terminated" url="http://focusvision.com" timeout="3">Thank you, but we are looking for someone a little different.</exit>
    <exit cond="overquota" url="http://focusvision.com" timeout="3">Thank you, but we’re a little full right now.</exit>
<var name="referer" />
</samplesource>

In the example above, respondents will see the specified exit message before being redirected to the FocusVision homepage after 3 seconds.

3.6: Close a Sample Source

Individual sample sources can be closed by adding closed="1" to the specific <samplesource> tag. Closing an individual sample source will prevent respondents from entering the survey for that particular sample source, but allow the rest of the survey to continue fielding.

<samplesource list="99" title="Open Sample" disableBrowserDupes="1" closed="1">
    <exit cond="1">Thank you for your time!</exit> 
</samplesource

In the example above, the Open Sample was closed. Respondents entering the survey with list="99" in their survey link will see a Survey Closed message. Respondents in the remaining two sample sources will be unaffected. 

4: Sample Source Results

The results of all changes to the sample sources are shown below.

<samplesources default="2">
 <samplesource list="1" title="EZ-Sample">
    <exit cond="qualified" url="http://focusvision.com" timeout="3">Thanks again for completing the survey!</exit>
    <exit cond="terminated and s2.val lt 18" url="http://focusvision.com" timeout="3">Try again when you’re a few years older.</exit>
    <exit cond="terminated" url="http://focusvision.com" timeout="3">Thank you, but we are looking for someone a little different.</exit>
    <exit cond="overquota" url="http://focusvision.com" timeout="3">Thank you, but we’re a little full right now.</exit>
    <var name="referer" />
 </samplesource>
 <samplesource list="2" title="Sample Co.">
    <invalid>Please double check your URL!</invalid>
    <inuse>You're already taking this survey!</inuse>
    <completed>You’re already done here...</completed>
    <var name="seg" required="1" values="1,2,3,4" />
    <var name="id" unique="1" filename="ids.dat"/>
    <exit cond="qualified" url="http://sampleco.domain.com/survey?stat=q&amp;seg=${seg}&amp;id=${id}"/>
    <exit cond="terminated" url="http://sampleco.domain.com/survey?stat=t&amp;seg=${seg}&amp;id=${id}"/>
    <exit cond="overquota" url="http://sampleco.domain.com/survey?stat=o&amp;seg=${seg}&amp;id=${id}"/>
 </samplesource>
 <samplesource list="99" title="Open Sample" disableBrowserDupes="1" closed="1">
    <exit cond="1">Thank you for your time!</exit>
 </samplesource>
</samplesources>

4.1: Survey Links

If multiple sample sources are added to a project, each sample source will have its own survey link. Each sample source will have the "list" variable added to the survey link to capture and track the source of sample. Any variables added to the sample source will also be present in the survey link.

To access the survey links, select Project Summary from the Test menu. An example of the Survey URLS in the Project Summary is shown below for the 3 sample sources configured in this article.

5: Respondent Timeline

When a new respondent enters a survey via one of the Survey Links provided above, the Sample Sources are evaluated before the respondent sees any survey questions. The timeline in which the Decipher system handles respondents entering the example survey is detailed below:

  1. The language for the study is determined and set.

  2. The URL is checked to identify which list variable is passed. If none is provided, the system looks for the default list to use in the <samplesouces> tag. If a default is not provided, the system will resort to the first <samplesource> specified. (e.g. "EZ-Sample")

  3. The <samplesource> used is checked for being closed. A respondent will not be allowed into the survey if <samplesource ... closed="1"> is set.

  4. The <samplesource> used is checked to confirm that all required variables are present.

  5. The <samplesource> variables that are validated against a file are checked.

  6. The <samplesource> variables that are unique are checked against previous completions.

  7. The <samplesource> variables that are unique are checked against respondents already in the survey but not yet completed. (15 minute inactivity timeout)

  8. If the respondent is approved, <samplesource>-specific markers are set and variables are recorded and marked as in-use.

  9. If the respondent finishes the survey, any unique <samplesource> variables are marked as completed.

  10. If the respondent finishes the survey, the <exit> links are used to redirect the respondent.