====== Working with External Panel Providers  ======

If you recruit the participants of your survey through a panel provider, you have to work with IDs, backlinks, exit links and redirects. This section describes how to implement it with SoSci Survey elegantly. 

===== Abstract =====

In most cases, it is sufficient to use the following steps.

Below is a more detailed explanation of what the different links are all about.

**Important:**  These steps are __not__ sufficient in multi-choice surveys, where a personal identifier must also be stored.


==== Share Link ====

Provide the panel provider with the link to the questionnaire and attach a ''?r=[panelID]''.

If your link to the questionnaire is ''%%https://s2survey.net/project/%%'', tell the panel provider that the link to the questionnaire is as follows:

<code>
https://s2survey.net/project/?r=[panelID]
</code>

==== Add Complete-Redirect ====

You probably received redirects for 3 or 4 different scenarios from the panel provider:

  * Complete -- the participant has completed the questionnaire
  * Screenout -- the participant is not suitable for the survey due to characteristics requested in the questionnaire
  * QuotaFull -- Sufficient questionnaires are already available for the demographic group(s) of the participant
  * Quality -- due to the answers (control questions, bogus items) or the speed of answering you have to assume that the questionnaire was not filled out meaningfully

In the simplest case, use the Complete URL. This could be, for example:

<code>
https://www.panelanbieter.de/complete?xyz=ABCDEF&uid=[panelID]
</code>

Under **Compose questionnaire**, insert an additional page before the "last page" in the questionnaire. Place the following PHP code there.

<code php>
redirect('https://www.panelanbieter.de/complete?xyz=ABCDEF&uid=%reference%');
</code>

Note that the wildcard ''[panelID]'' in the original redirect (this may be different) has been replaced by a [[:en:create:placeholders|SoSci placeholder]] ''%reference%''.

==== Screenout etc. ====

You can still place the other redirects elsewhere in the questionnaire if you like. The use of quota stops and screenout is described in chapter [[:en:survey:quota]]. A quality check at the end could look like this -- to be placed just above the Complete redirect.

<code php>
if ((value('MISSING') > 20) || (caseTime('begin') < 300)) {
  redirect('https://www.panelanbieter.de/quality?xyz=DEFGHI&uid=%reference%');
}
</code>

The further instructions explain the background of the Complete-Redirect.

===== The Meaning Behind the Many Links  =====

If the provider of a panel pays a fee to the participants, he would like to know who has the questionnaire at all completed course. To this end, he must "follow" the individual participant. 

  * A ParticipationID (TIC)\\ Whenever a provider of a panel sends invitations to a questionnaire he creates an unique individual ID. The provider saves this ID intern and which emailadress got an invitation to which questionnaire. The ID ''12345xyz'' could name the participant ''12345'' who got the invitation to the questionnaire ''xyz''.
  * A PersonsID (optional, INFO)\\ This identifier is relevant in multi-wave surveys, it clearly identifies the panelist:in to whom the invitation was sent. Thus, the identifier ''GHIJ765'' could denote the panelist:in ''12345'' in your survey. For privacy reasons, the same individuals in different studies may be assigned different personal identifiers.

==== Data in Internet Adresses ====

The communication between panels and SoSci Survey runs (mostly) via GET parameters in the URLs. More about the [[en:survey:url]] and redirect links soon. First of all, it is essential that an Internet address can have several components:

{{:de:survey:fig.panel.url.png?nolink|Parts of URL}}

At first there is the internet adress (which has different parts by it self). To this can --devided per questionmark-- more data be connected. These data are pairs of a name (key) and a key, where an equal is written between them. Several pairs are devided with an ampersan (''&''). In the example above the pairs ''tic=ABCDEF9876'' and ''pid=GHIJ765'' are send to the adress ''%%https://www.soscisurvey.de/project/%%''.

This means: If a person opens this URL in a browser, two values as send to the questionnaire ''www.soscisurvey.de/project''. But at first these values are not saved in the dataset.

==== Communication between Panel and Questionnaire ====

The panel provider has to bill if a panelist filled the questionnaire. The questionnaire has to inform the panel provider if the questionnaire is filled. The communication runs via the panelists browser. Spoiler ahead: If the panelist sends the redirect URL (UPL/R) and the participation ID (TIC) to the provider it counts as successful participation an gets billed.

{{:de:survey:fig.panel.links.png?nolink|Communication between panel and Questionnaire}}

  * (1) After the booking of a sample by a panel provider you get normally a redirect link. Actually not only one, but different ones for successful participation (complete), for unsuitable participants (screenout/quotafull) and for sloppy participants (quality/qualityfail).
  * (2) These links have to be put at appropriate times in the questionnaire. How to do this is explained in this manual.
  * (3) Furthermore you have to tell the panel provider the questionnaires link. You must also agree with the panel provider what names the parameters for the subscriber ID (TIC) and for any other data should have. If you take the name ''r'' for participation IDs you save work (see above). In the example the name ''tic'' was used. Usually, you immediately inform the panel provider of an Internet address that contains your questionnaire URL ([[:en:survey:url]]) and a wildcard for the TIC (see above).

GET data with the name ''r'' are automatically saved as reference in the dataset ([[en:survey:url#marking_a_url_r|The Link to the questionnaire]]). To save data with another name you need a question of the type [[:en:create:questions:client|Device and transmitted variables]].

After a view tests with you and the provider the study can start. Now, hopefully the panel provider serches for successful participants for your study and creates a individual participants ID (TIC).

  * (4a) In the questionnaire link (URL/F), the panel provider puts a different participation ID (TIC) for each panelist:in. The provider sends this link to the participant or offers it in his website. How the panelist:in gets the link is ireelevant -- important is that the panelist:in clicks on the link.
  * (4b) By clicking the internet adress it gets opend at the browser. This means, that the panelist's browser sends the data that are in the link to the adress of the link. The address belongs to your questionnaire, so the data (TIC and INFO, if applicable) will be sent to your questionnaire. There the data have to be collected and saved.

Now the interview starts and the panelist dills the sides of the questionnaire. Sooner (Screenout/[[:en:survey:quota|Quotenstop]]) or later he gets to the page with the ''[[:en:create:functions:redirect]]''.

  * (5a) The ''redirect()'' function sends the panelist:in's browser a request to call a new URL, namely the redirect URL (URL-R) along with the subscriber ID (TIC). You build this Internet address based on the information from the panel (URL-R) and the previously received subscriber ID (TIC).
  * (5b) The browser gets the request and opens the according adress. In this way the data (TIC) are send back to the panel provider.

The panel provider now registers the call of his redirect upl with the specific TIC. Thereby he knows that the panelist:in has filled in the questionnaire. Or he knows that the panelist is dismissed depending on the called redirect link.

What is the additional data (INFO) about? This can be, for example, a personal identifier or demographic data about the panelist. The panel provider possibly sends this data connected to the TIC and you have to make sure that the data are saved in the dataset.

  * (6) After the survey all data are available which the panel provider send __and__ you have saved. In any case, check directly after the first tests whether all necessary data (in multi-wave surveys especially a person ID) are available in the data set.



===== Personalized Links to the Questionnaire  =====

The easiest way for the panel provider is to submit the identifier as a reference. For this purpose, the variable ‘‘r’’ must be attached to the link of the questionnaire. The address is then ‘’%%ServerURL/project/?r=Identifier%%’’, e.g. ‘’%%https://www.soscisurvey.de/demo/?r=Identifier%%’’. 

The provider will exchang the //identifier// for each participant. 

**Note**: If you do not want to call the standard questionnaire in the link, use the link only once the question mark (‘’?’’) and for other variables, the ampersand (‘’&’’), e.g. ‘’%%https://www.soscisurvey.de/demo/?q=fb2&r=Identifier%%’’. To create the links see also [[url | The link to the questionnaire]]. 

**Note**: If the provider wants to use a different variable necessarily instead of the variable ‘’r’’, then you only need two more lines of PHP code, which is below. 

===== Exit-links back to the provider  =====

In order to inform the participant identifier to the provider end of the survey, the participant is simply redirected to a website of the provider. Once again, the identifier is transmitted. 

Vom Anbieter erhält man üblicherweise einen Exit-Link der etwa so aussieht:\\ ''%%http://www.provider.com/p9815245/exit.php?id=Code%%''
Instead of the //code// you must now use the reference that you got in the beginning with each respondent. This can be done simply with the placeholder ‘’reference’’: \\
''%%http://www.anbieter.com/p9815245/exit.php?id=%reference%%%''

Now you have to only redirect the respondents - the so-called Redirect. You can use the function  ''[[:en:create:functions:redirect|redirect()]]''. However, this breaks the survey immediately and directs the participants to another page. So you have to insert a blank page itself before the end of the questionnaire, and paste the//PHP-Code/// and then the ''redirect()''command: 

<code php>
redirect('http://www.anbieter.com/p9815245/exit.php?id=%reference%');
</code>

You should put nothing else on this page. 

If one invokes the questionnaire with a test identifier and the link above (which you simply invent yourself), then you should be redirected at the end of the survey to the page of the provider and in the address line of the browser you should see the test-identifier. Probably you will get an error message from the provider, because the identifier is not valid. 

**Hint:** With the ''redirect()'' function participants can be also send away when the contigent is met. Whether the contigent has been met, you can, for example, check this by using the ''[[:en:create:functions:statistic|statistic()]]'' function.

**Important:** If a participant leaves the questionnaire with  ''redirect()'' then the questionnaire is marked as incompleted in the data record. To filter incomplete data records, you have to go back to the last completed page (LAST PAGE).

**Important:** If you want to use the placeholder ''%reference%'', then you must not prepare a placeholder named ''%reference%'' using ''[[:de:create:functions:replace|replace()]]''.

===== The provider uses a different variable as the "r"  =====

If the provider can not or doesn’t want to use r in the link or wants to set a variable such as susid, it is also pretty easy to solve. The variable for this is read in on the first (!) page in the questionnaire with a question of the type [[:en:create:questions:client|Device and transmitted variables]]. Enter the name of the variable containing the panel identifier (e.g. "userID").

{{:de:survey:scr.panel.client.png?nolink|Question of type: Device and transmitted variables}}

As a wildcard in the links, one must then of course specify the name of the variable as it is stored in the data set. If the variable for reading in is called ''DV01_RV1'', for example, one would set the wildcard as follows:

<code php>
// This code can be found under the question "Device and transmitted variables".
// or be placed before the forwarding
replace('%panelID%', 'DV01_RV1', 'response');  // Prepare wildcard
</code>

<code php>
// PHP code for redirect
redirect('http://www.anbieter.com/p9815245/exit.php?id=%panelID%');
</code>

Instead of using ''replace()'', you can also work directly with ''value()'' and the PHP operator for joining strings (''.''). The following PHP code leads to the same result as the two PHP codes above.

<code php>
// PHP-Code für Redirect
redirect('http://www.anbieter.com/p9815245/exit.php?id='.value('DV01_RV1'));
</code>


===== Panels and randomized sample =====

A normal [[:en:create:randomization]] has no effect on the panel connection, but if you implement a [[:en:create:random_questionnaire]] using ''[:en:create:functions:gotoquestionnaire]'', you must pass the panel ID (and other variables if required) to the subordinate questionnaires.


Here you can see the process described in detail: [[:de:create:random_questionnaire#zusammenspiel_mit_externen_panels|Zusammenspiel mit externen Panels]]


===== Searching for mistakes =====

If you send the panel provider the questionnaire link (mit Platzhalter für die Panel-ID, look at [[#link_mitteilen|Link mitteilen]] and [[#personalisierte_links_zum_fragebogen|Personalisierte Links zum Fragebogen]]) , then he will check if the Redirects are working. 

If this is not working there are three possible reasons why:

  - The panel ID is not correctly transferred to the questionnaire by the panel provider
  - The panel ID is not correctly returned to the panel provider in the redirect
  - The ''redirect()'' function is not called due to the filter guidance

To narrow down the problem, first search for the test data sets generated by the panel provider under **Collected data** -> **View data**. If you cannot find any suitable cases there, check again whether you have sent the panel provider the links to the correct survey project.

In the data cases, check whether there is a panel ID. This is usually a long number or a cryptic code consisting of numbers and letters. If you are working with ''r='', the code should be saved in the variable "REF". If you read in the code with a question "Device and transmitted variables", then search under the identifier of this question. If the code is not available, ...

  * you have either sent the panel provider an incorrect link.
  * Or in the **Project settings** under //Special// a different variable name was specified for the reference in //Variables in the link to the questionnaire//.
  * Or the question "Device and transmitted variables" was not placed on the first page of the questionnaire.
  * Or you have defined several questionnaires in the project (**Compile questionnaire** -> **Manage questionnaires**) and the wrong one is being called up.

If the panel ID is saved in the data record but is not transmitted back, first check your redirect links again and whether the placeholders have been inserted correctly.

**Tip:** To test, you can simply start the questionnaire with a panel ID of your choice. So if the link is ''%%https://s2survey.net/project/?r=[panelID]%%'', then enter the following in the address bar of your browser: ''%%https://s2survey.net/project/?r=Test0001%%''. After the redirect (if it works) you will probably get an error message from the panel provider's website ... but that's okay, because there is no panel ID "Test0001" in their database. However, you can see whether the panel ID appears in the address line.


===== Panel-Providers =====

Below we link to the instructions from panel providers known to us.

  * [[https://www.sona-systems.com/help/soscisurvey/|Sona Systems: External Study Credit Granting with SoSci Survey]]