====== URL to the Questionnaire ====== Every website needs its URL. So does your questionnaire. To lead questionees to your questionnaire, they will need this address. This chapter gives tips on how to best use the URL and what possibilities you have. ===== The Survey'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/%%''. You will find your survey's URL under **Survey Project** -> **Project Settings** -> Tab //Publish Survey// -> //Questionnaire Hyperlink (URL)//. There you can also change the project's folder -- but only as long as the //survey adminitsration period// has not started yet. If necessary, you can change the survey period at any time (e.g. set the start of the period to tomorrow's date). **Note:** If you omit the slash at the end, the participant will still be automatically forwarded to the directory -- you can see that the slash in the address line of the browser is added. This redirection will take a short moment, however. ===== Parameter in the Questionnaire Link ====== In the link you can send SoSci Survey further instructions and information. For example, which questionnaire should be opened (if there are several questionnaires in the project) or that the dataset has a marker/reference (e.g. the subgroup that the participant belongs to). ==== Parameters ===== The instruction/information (parameters) always have the same structure: There is a key that specifies which parameter it is, and a value that is to be transmitted for this parameter. Parameters or keys are available: * [[#selection_of_a_questionnaire_q|Selection of a Questionnaire (q)]] (if several questionnaires were created in the project) * [[#marking_a_url_r|Marking a URL (r)]] (Variable REF) * [[#access_code_s|Access Codes (s)]] (variable SERIAL) * [[#specify_a_language_l|Specify a language (l)]] (for multilingual survey projects) * [[#password_password|Password (password)]] (for a password-protected questionnaire * [[#interview_token_i|Interview Token (i)]] (to continue an interrupted interview) * [[#participation_code_serial_mail_d|Participation code serial mail (d)]] (will be generated automatically by mailings) * You can also submit [[#user_defined_variables|User defined variables]]. ==== Using Parameters in the Link ===== To set parameters in the link, you need to learn a little about the GET syntax of the HTTP protocol: * Between key and value there is an equal sign (''=''')\\ ''q=questionnaire2'' * Several parameters are separated by an ampersand (''&'')\\ ''q=questionnaire2&r=g1'' * Between the survey URL (see above) and the parameter there is a question mark (''?'')\\ ''%%https://www.soscisurvey.de/demo/?q=questionnaire2&r=g1%%''. ==== Notes ==== **Warning:** When you insert a link in Outlook or Word, a distinction is made between the text that is displayed and where the link actually points (for testing: [[https://duckduckgo.com/?q=hyperlink|www.soscisurvey.de]]). If you change something in the link, then you may only change the text, but not the link behind it! **Note:** To use the parameters documented below, __no__ adjustments are required in SoSci Survey or in the //Project Settings//. Just copy the [[#the_survey_s_url|the survey's URL]] (e.g. ''%%https://www.soscisurvey.de/example/%%''), write the parameters (e.g. ''%%?r=Berlin%%%'') behind it and insert the link (''%%https://www.soscisurvey.de/example/?r=Berlin%%'') in an email or as a link on a website. **Note:** Please read [[#using_parameters_in_the_link|above]] what the question mark (''?'') and the ampersand (''&'') are all about and how they are used in the link. **Note:** The keys for the parameters can be adjusted under **Survey Project** -> **Project Settings** -> Tab //Expert Settings// -> //Variables in the Questionnaire's URL//. Normally this is __not__ necessary and we generally advise against changing the keys. ===== Example ===== In a survey project 3 target groups are addressed. In the survey project two questionnaires "q1" and "q2" are created. The target groups "A" and "B" should receive the questionnaire "q1" and target group "C" the questionnaire "q2". The data record should then show to which target group each row of data belongs. Target group "A" is addressed in a forum. The following link will be placed there: https://www.soscisurvey.de/demo/?r=A&q=q1 Target group "B" is recruited via a banner. The banner calls the following link: https://www.soscisurvey.de/demo/?r=B&q=q1 Target group "C" is invited by email. The following link will be sent via the company's email distribution list: https://www.soscisurvey.de/demo/?r=C&q=q2 If the questionnaire is called up via the first link, the value "A" is stored in the data record in variable "REF" - correspondingly "B" and "C" are stored for the other two links. **Important:** Please read the [[#notes|notes]] (above). ===== 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. This is used whenever the link to the survey project is called without a more detailed specification of a questionnaire. If necessary, you can also include a [[:en:create:random_questionnaire]] in this questionnaire. The selection of a questionnaire in the link is done by the parameter ''q'' and the identifier of the desired questionnaire. So to select the questionnaire "fb" in the project "demo" you would send e.g. the following link: https://www.soscisurvey.de/demo/?q=fb **Tip:** If you have created several questionnaires in the survey project, you will already find all corresponding //Internet addresses (URLs) for calling up a questionnaire// listed under **Create questionnaire** -> **Manage questionnaires**. **Tip:** If you [[:en:survey:mailing|Serienmail versenden]], then set the desired questionnaire directly in the serial mail in the tab //questionnaire link//. The selection of the questionnaire is then stored together with the other settings in the individual participation link. ===== 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 (_). **Important:** Please read the [[#notes|notes]] (above). ===== Access Code (s) ===== A special case of marking is the access code ([[:en:survey:serials]]). This is a one-time-password that allows him to access a questionnaire using the [[:en:create:access|access restriction]] //Access code//. For this to work, every participant needs his valid access code. They don't need to type it in by himself, instead add the access as the parameter ''s'' to the URL: ''%%https://www.soscisurvey.de/demo/?s=AB123456%%'' Access codes must only contain letters (A-Z) and digits (0-9). **Tip:** When sending personalized URLs using access codes, participants are able to pause the interview and resume it later where they left off. This even works for questionnaires that are public. Nevertheless, every participant needs to have their own access code beforehand. **Important:​** An individual access code is only valid until the questionnaire was filled out and reached the last page. Afterwards, the access code won't work, any more. ===== 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 access code (because those are one-time only). ===== 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%%''. ===== Participation Code Serial Mail (d) ===== If sending a mailing via 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 mailing and every participant. So the parameter ''d'' should be left to the software and should not be used by yourself. ===== Custom Variables ===== Using the question type ''[[:en:create:questions:client]]'' or the PHP function ''[[:en:create:functions:readget#readget|readGET()]]'' allows you to read user defined variables from the request URL. In addition to the variables listed above (''q'', ''r'', ''s'', ''d'', ''i'', ''l'', ''password''), the following reserved variables should not be used to pass user-defined data: ''a'', ''act'', ''adid'', ''ajax'', ''debug'', ''file'', ''image'', ''info'', ''library'', ''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.