====== URL to the questionnaire ======

Every website needs its URL. So does your questionnaire. To lead questionees to your questionnaire, they will need this adress. This chapter gives tips on how to best use the URL and what possibilities you have.

===== The questionnaire's URL =====

The URL of your questionnaire is put together from SoSciSurvey's URL (''%%https://www.soscisurvey.de%%'') and the project directory (e.g. ''demo''). Between those components is a slash (''/''). There is a slash at the end of the address as well, because the address refers to a directory, not a file: ''%%https://www.soscisurvey.de/demo/%%''.
Although, if the slash is been left out, the user will be redirected to the directory (you'll see that the browser will suddenly show the slash anyway). This redirection will take a short moment, however.

===== Parameters of the URL =====

To set more parameters in the link, you should know about the GET-syntax of the HTTP-protocol. You need to tell SoSciSurvey what you want through the URL.

There is the parameter ''q'' (//questionnaire//) that can be used to choose a specific questionnaire of a project. Another parameter is ''r'' (//reference//) which "marks" the hyperlink (see below).

Those parameters consist of the variable's name (e.g. ''q'' or ''r'') and its respective value. In between is a equal sign (''=''). So, if the questionnaire you want has the ID (Name) "qn1" and the reference is "banner", the parameters are ''q=qn1'' and ''r=banner''. Several parameters are concatenated by using a ''&''-sign: ''q=qn1&r=banner''.

Those parameters are attached to the original URL, using a question mark (''?''). The whole URL looks like this: ''%%https://www.soscisurvey.de/demo/?q=qn1&r=banner%%''.

If the browser calls this address, the website %%https://www.soscisurvey.de/demo/%% is requested and the two parameters are sent. As SoSciSurvey knows what to do with those parameters, it will use ''q'' to select a questionnaire and saves the value for ''r'' into the database.

===== Selection of a questionnaire (q) =====

In case you have created more than one questionnaire in your survey project, you can decide, which questionnaire is being shown. You have two options on how to do this (see also: [[:de:create:random_questionnaire|Random Questionnaires]]:

  - //Standard questionnaire//: If only one questionnaire (of several created questionnaires) should be shown, you can define the standard questionnaire at **Compose Questionnaire** -> Further Questionnaires -> //Random selection for questionnaires//. Whenever the project directory is called with __no further__ ''q''-parameters, it will open the standard questionnaire.
  - //Specific selection//: To select a specific questionnaire, use the parameter ''q'' and the questionnaire's ID (Name). To choose the questionnaire "qn" in the project "demo", use: ''%%https://www.soscisurvey.de/demo/?q=qn%%''.
  - //Random selection//: In case you want SoSciSurvey to choose randomly between several questionnaires, set this at **Compose Questionnaire** -> Further Questionnaires -> //Random selection for questionnaires//. Whenever the project directory is called with __no further__ ''q''-parameters, it will open a randomly chosen questionnaire.

===== Marking a URL (r) =====

If you want to track where your participants come from (e.g. you invited them by email and via Facebook and want to see which was more successful), you might want to "mark" the URL.

This is also useful, if you would like to save a unique ID for participants into the dataset. E.g. when sending two questionnaires to two different people that belong together (wife and husband) and you want to be able to allocate those later on, you can send them a link with the same ID (in this case you are able to send them different questionnaires by using different ''q'', but same ''r''-parameters).

You do this by using the parameter ''r''. The text following the parameter will simply be saves as a variable REF into the dataset. So when someone clicks the link ''%%https://www.soscisurvey.de/demo/?r=12345%%'' you will find the reference "12345" in the dataset.

**Advice:** In general, you are able to use any signs except single and double quotes (''%%'%%'' and ''%%"%%''), equal-signs (''%%=%%'') and the ampersand (''&''). However, spaces and other special signs can cause problems depending on browser interpretation. To avoid any problems, use only letters, numbers and the underscore (_).

===== Delivering a serial (s) =====

A special case of marking is the serial. This is a one-time-password that allows him to access a questionnaire using [[:de:create:access|Access restrictions]].

For this to work, every participant needs his valid serial. He doesn't need to type it in by himself -- this is why the serial can be added as the parameter ''s'' to the URL: ''%%https://www.soscisurvey.de/demo/?s=AB123456%%''

**Tip:** When sending personalized URLs using serials, participants are able to interrupt the interview and resume it later where they left off. This even works for questionnaires that are basically public. Nevertheless, every participant needs to have his own serial beforehand.

**Important:** An individual serial is only valid until exactly one questionnaire is completed. Afterwards, the serial is used up.

===== Participation code serial mail (d) =====

If sending a serial mail using SoSciSurvey and using the placeholder ''%link%'' for personalized links, SoSciSurvey will attach the parameter ''d'' (delivery ID).

This is a software-internal code that is being recreated for every serial mail and every participant. So the parameter ''d'' should be left to the software and should not be used by yourself.

===== Specify a language (l) =====

If several languages are available to the questionnaire, you can specify it using the parameter ''l''. After the equal sign, place the three-figure language code. The statement in the URL overwrites the language setting of the questionnaire.

Example: ''%%https://www.soscisurvey.de/demo/?l=ger%%''

===== Password (password) =====

In case you have secured your questionnaire by passwords, you can deliver those in the link. The parameter is ''password''. If the password was "secret123", the following link would give access to the questionnaire: ''%%https://www.soscisurvey.de/demo/?password=secret123%%''.

However, it is not reasonable to post a link containing a password publicly on a webpage. This makes the password protection useless. Using this parameter is more useful when inviting participants via email. But the more secure way is using the serial mail or the serial number (because those are one-time only).

You can use the parameter ''password'' to send the password for pretest links (see example below).

===== Variing the pretest-mode (debug) =====

When a questionnaire is in pretest, the participants can receive a particular pretest-version with a feedback option or the original questionnaire. The first one is standard when your survey is in pretest. Stating the parameter ''debug'' (with no value this time), will call for the original version: ''%%https://www.soscisurvey.de/demo/?debug%%''.

If you want to lead pretesters to the original version without them having to type a password, you can combine the parameters ''debug'' and ''password'': ''%%https://www.soscisurvey.de/demo/?debug&password=secret123%%''.


===== Interview Token (i) =====

Each interview has an unique token (ID string). This token is accessible via [[:en:create:functions:casetoken]] or the placeholder ''%caseToken%''.

If a suspended interview's token is known (e.g., because it was sent to an external website), the interview can be resumed, using the ''i'' parameter containing the token: ''%%https://www.soscisurvey.de/demo/?i=12345abcde%%''.


===== User defined variables =====

Using the PHP-function ''[[:en:create:functions:readget#readget|readGET()]]'' allows you to call user defined variables from the questionnaire's URL.

You should not use the above variables (''q'', ''r'', ''s'', ''d'', ''l'', ''password'', ''debug'') as well as the following: ''a'', ''act'', ''adid'', ''ajax'', ''file'', ''image'', ''info'', ''script'', ''sp'', ''t''

To ensure your user defined variables won't collide with standard variables, choose a name starting with ''u''. Those are explicitly reserved for user defined variables.