====== Mit externen Panel-Anbietern arbeiten ======

Sofern Sie die Teilnehmer Ihrer Befragung über einen Panel-Anbieter rekrutieren, müssen Sie mit IDs, Backlinks, Exit-Links und Redirects arbeiten. Dieser Abschnitt beschreibt, wie Sie das mit SoSci Survey elegant implementieren.


===== Kurzfassung =====

In den meisten Fällen reicht es aus, wenn Sie die folgenden Schritte verwenden.

Unten wird genauer dargelegt, was es mit den unterschiedlichen Links auf sich hat.

**Wichtig:** In mehrweilligen Befragungen sind diese Schritte __nicht__ ausreichend, dort muss zusätzlich noch eine Personenkennung gespeichert werden.


==== Link mitteilen ====

Teilen Sie dem Panel-Anbieter den Link zum Fragebogen mit und hängen Sie ein ''?r=[panelID]'' an.

Wenn Ihr Link zum Fragebogen ''%%https://s2survey.net/project/%%'' lautet, so teilen Sie dem Panel-Anbieter mit, dass der Link zum Fragebogen wie folgt lautet:

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

==== Complete-Redirect einfügen ====

Sie haben vom Panel-Anbieter wahrscheinlich Redirects für 3 oder 4 verschiedene Szenarien erhalten:

  * Complete -- der Teilnehmer hat den Fragebogen vollständig abgeschlossen
  * Screenout -- der Teilnehmer ist aufgrund im Fragebogen abgefragter Eigenschaften nicht für die Erhebung geeignet
  * QuotaFull -- für die demografische Gruppe(n) des Teilnehmers liegen bereits ausreichend Fragebögen vor
  * Quality -- aufgrund der Antworten (Kontrollfragen, Bogus Items) oder der Antwortgeschwindigkeit müssen Sie davon ausgehen, dass der Fragebogen nicht sinnvoll ausgefüllt wurde

Im einfachsten Fall verwenden Sie die Complete-URL. Diese könnte z.B. lauten:

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

Fügen Sie unter **Fragebogen zusammenstellen** vor der "letzten Seite" im Fragebogen eine zusätzliche Seite ein. Dort platzieren Sie folgenden PHP-Code.

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

**Wichtig:** Beachten Sie, dass der Platzhalter ''[panelID]'' im ursprünglichen Redirect (dieser kann auch anders lauten) durch einen [[:de:create:placeholders|SoSci-Platzhalter]] ''%reference%'' ersetzt werden muss.

==== Screenout etc. ====

Sie können an anderer Stelle im Fragebogen noch die anderen Redirects platzieren, wenn Sie möchten. Die Verwendung von Quotenstopps und Screenout ist im Kapitel [[:de:survey:quota]] beschrieben. Eine Qualitätsprüfung am Ende könnte wie folgt aussehen -- zu platzieren direkt oberhalb des Complete-Redirects.

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

Die weitere Anleitung erklärt die Hintergründe zum Complete-Redirect.


===== Der Sinn hinter den vielen Links =====

Sofern der Anbieter eines Panels den Teilnehmern eine Vergütung zahlt, möchte er natürlich gerne wissen, wer den Fragebogen überhaupt vollständig ausgefüllt hat. Dazu werden mithilfe der Links einige Daten zwischen dem Panel-Anbieter und SoSci Survey übermittelt. Dieses sind:

  * Eine Teinahme-ID (TIC)\\ Wann immer der Panel-Anbieter Einladungen für Ihren Fragebogen verschickt, erstellt er für jede:n Panelist:in eine einmalige, individuelle Kennung. Intern speichert der Panel-Anbieter diese Kennungen und welche E-Mail-Adresse zu welchem Fragebogen eingeladen wurde. Die Kennung ''ABCDEF9876'' könnte z.B. dafür stehen, dass Panelist:in ''12345'' zum Fragebogen ''XYZ'' eingeladen wurde.
  * Eine Personenkennung (optional, INFO)\\ Diese Kennung ist in mehrwelligen Erhebungen relevant, sie bezeichnet eindeutig die Panelist:in, an welche die Einladung verschickt wurde. Die Kennung ''GHIJ765'' könnte also in Ihrer Erhebung die Panelist:in ''12345'' bezeichnen. Aus Datenschutzgründen bekommen dieselben Personen in unterschiedlichen Studien u.U. unterschiedliche Personenkennungen zugewiesen.


==== Daten in Internetadressen ====

Die Kommunikation zwischen Panel und SoSci Survey erfolgt (meistens) über GET-Parameter in den URLs. Zu den URLs ([[:de:survey:url]] und Redirect-Links) gleich noch mehr. Wesentlich ist zunächst, dass eine Internetadresse mehrere Bestandteile haben kann:

{{:de:survey:fig.panel.url.png?nolink|Bestandteile einer URL}}

Da ist zunächst die eigentliche Internetadresse (die ihrerseits nochmal unterschiedliche Bestandteile hat). An diese können aber -- getrennt durch ein Fragezeichen -- weitere Daten angehängt werden. Diese Daten sind jeweils Paare aus einem Namen (key) und einem Wert (value), wobei zwischen Name und Wert ein Gleichheitszeichen steht. Mehrere solcher Paare werden mit einem kaufmännischen Und (''&'') getrennt. Im obigen Beispiel werden also die Paare ''tic=ABCDEF9876'' und ''pid=GHIJ765'' an die Adresse ''%%https://www.soscisurvey.de/project/%%'' übermittelt.

Das bedeutet: Wenn eine Person diese URL im Browser öffnet, dann werden an den Fragebogen ''www.soscisurvey.de/project'' zwei Werte übermittelt. Allerdings werden diese Werte zunächst nicht im Datensatz gespeichert.


==== Kommunikation zwischen Panel und Fragebogen ====

Der Panel-Anbieter muss abrechnen, wenn eine Panelist:in den Fragebogen ausgefüllt hat. Ob der Fragebogen ausgefüllt wurde, muss der Fragebogen dem Panel mitteilen. Die Kommunikation läuft dabei über den Browser der Panelist:in. Spoiler vorweg: Wenn die Panelist:in die Redirect-URL (URL/R) und die Teilnahme-ID (TIC) an den Panel-Anbieter übermittelt, dann wird das als erfolgreiche Teilnahme gezählt und abgerechnet.

{{:de:survey:fig.panel.links.png?nolink|Kommunikation zwischen Panel und Fragebogen}}

  * (1) Nach der Buchung eines Samples beim Panel-Anbieter erhält man in aller Regel einen Redirect-Link. Genau genommen nicht nur einen, sondern unterschiedliche für erfolgreiche Teilnahmen (complete), für ungeeignete Teilnehmer:innen (screenout/quotafull) und für schlampige Teilnehmer:innen (quality/qualityfail).
  * (2) Diese Links müssen Sie an geeigneter Stelle in den Fragebogen einbauen. Wie das funktioniert, wird in dieser Anleitung erklärt.
  * (3) Weiterhin müssen Sie dem Panel-Anbieter den Link zum Fragebogen mitteilen. Außerdem müssen Sie sich mit dem Panel-Anbieter abstimmen, welche Namen die Parameter für die Teilnehmer-ID (TIC) und für eventuelle weitere Daten haben sollen. Wenn Sie für die Teilnahme-ID den Namen ''r'' verwenden, sparen Sie sich etwas Arbeit (siehe oben). Im Beispiel hier wurde der Name ''tic'' verwendet. Für gewöhnlich teilen Sie dem Panel-Anbieter gleich eine Internetadresse mit, welche Ihre Fragebogen-URL ([[:de:survey:url]]) und einen Platzhalter für die TIC enthält (siehe oben).

GET-Daten mit dem Namen ''r'' werden automatisch als Referenz (REF) im Datensatz gespeichert ([[:de:survey:url#einen_link_markieren_r|Der Link zum Fragebogen]]). Um Daten mit einem anderen Namen zu speichern benötigen Sie eine Frage vom Typ [[:de:create:questions:client|Gerät und übermittelte Variablen]] erstellen.

Nach einigen Tests durch Sie und den Panel-Anbieter kann die Studie dann ins Feld starten. Nun sucht der Panel-Anbieter (hoffentlich) geeignete Personen für die Studie heraus und erzeugt für jede Person eine einmalige Teilnehmer-ID (TIC).

  * (4a) In den Fragebogen-Link (URL/F) setzt der Panel-Anbieter für jede Panelist:in eine andere Teilnahme-ID (TIC) ein. Diesen Link sendet der Panel-Anbieter dann an die Panelist:in oder bietet ihr den Link auf der eigenen Website an.  Wie die Panelist:in an die URL kommt, ist für die Befragung irrelevant -- wesentlich ist, dass die Panelist:in den Link anklickt.
  * (4b) Durch Klick auf die Internetadresse wird diese im Browser geöffnet. Das bedeutet, dass der Browser der Panelis:in die Daten im Link an die im Link angegebene Adresse sendet. Die Adresse gehört zu Ihrem Fragebogen, also werden die Daten (TIC und ggf. INFO) an Ihren Fragebogen übermittelt. Dort müssen die Daten entgegengenommen und gespeichert werden.

Nun startet erst einmal das Interview und die Panelist:in füllt die Seiten des Fragebogens aus. Früher (Screenout/[[:de:survey:quota|Quotenstop]]) oder später kommt sie dann auf die Seite mit dem ''[[:de:create:functions:redirect]]''.

  * (5a) Die Funktion ''redirect()'' sendet dem Browser der Panelist:in die Aufforderung, eine neue URL aufzurufen, nämlich die Redirect-URL (URL-R) zusammen mit der Teilnehmer-ID (TIC). Diese Internetadresse bauen Sie auf Basis der Informationen vom Panel (URL-R) und der vorher empfangenen Teilnehmer-ID (TIC) zusammen.
  * (5b) Der Browser erhält vom Fragebogen die Aufforderung und ruft entsprechend die Adresse auf. Dadurch werden die Daten (TIC) an den Panel-Anbieter zurück übermittelt.

Der Panel-Anbieter registriert nun den Aufruf seiner Redirect-URL mit der spezifischen TIC. Dadurch weiß er, dass die Panelist:in den Fragebogen ausgefüllt hat. Oder dass sie durch einen Screenout abgewiesen wurde, je nachdem welche Redirect-URL aufgerufen wurde.

Was hat es mit den zusätzlichen Daten (INFO) auf sich? Das kann zum Beispiel eine Personenkennung sein oder es können demografische Daten zur Panelist:in sein. Diese Daten übermittelt der Panel-Anbieter eventuell gemeinsam mit der TIC und Sie müssen dafür sorgen, dass die Daten im Datensatz gespeichert werden.

  * (6) Nach der Erhebung stehen alle Daten im Fragebogen zur Verfügung, welche Sie vom Panel-Anbieter übermittelt bekommen __und__ gespeichert haben. Prüfen Sie auf alle Fälle direkt nach den ersten Tests, ob alle notwendigen Daten (in mehrwelligen Erhebungen insbesondere eine Personenkennung) im Datensatz vorliegen.


===== Personalisierte Links zum Fragebogen =====

Am einfachsten übermittelt der Panel-Anbieter die Kennung als Referenz. Dazu muss an den Link des Fragebogens die Variable ''r'' angehängt werden. Die Adresse lautet dann ''%%ServerURL/projekt/?r=Kennung%%'', also z.B. ''%%https://www.soscisurvey.de/demo/?r=Kennung%%''.

Die //Kennung// tauscht der Anbieter natürlich für jeden Teilnehmer aus.

**Hinweis:** Falls Sie nicht den Standard-Fragebogen im Link aufrufen möchten, verwenden Sie im Link nur einmal das Fragezeichen (''?'') und für weitere Variablen das kaufmännische Und (''&''), z.B. ''%%https://www.soscisurvey.de/demo/?q=fb2&r=Kennung%%''. Zum Erstellen des Links s. auch [[url|Der Link zum Fragebogen]].

**Hinweis:** Falls der Anbieter statt der Variable ''r'' unbedingt eine andere Variable verwenden will, dann benötigt man nur 2 Zeilen mehr PHP-Code. Welchen, das steht weiter unten.

===== Exit-Links zurück zum Anbieter =====

Um nun die Teilnehmer-Kennung am Ende der Befragung dem Anbieter mitzuteilen, wird der Teilnehmer einfach auf eine Website des Anbieters umgeleitet. Dabei wird wiederum die Kennung übermittelt.

Vom Anbieter erhält man üblicherweise einen Exit-Link der etwa so aussieht:\\ ''%%http://www.anbieter.com/p9815245/exit.php?id=Code%%''

Anstatt //Code// muss man nun bei jedem Befragten die Referenz einsetzen, die man am Anfang bekommen hat. Dies erledigt man einfach mit dem Platzhalter ''reference'':\\
''%%http://www.anbieter.com/p9815245/exit.php?id=%reference%%%''

Jetzt muss man den Befragten nur noch umleiten -- das so genannte Redirect. Dazu gibt es die Funktion ''[[:de:create:functions:redirect|redirect()]]''. Allerdings bricht diese die Befragung sofort ab und leitet den Teilnehmer auf eine andere Website um. Man muss also im Fragebogen selbst vor dem Ende eine leere Seite einfügen, dort //PHP-Code// einfügen und dort den ''redirect()''-Befehl:

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

Sonst sollte man auf der Seite nichts mehr unterbringen.

Wenn man nun den Fragebogen mit einer Test-Kennung und dem oben gebastelten Link aufruft (die man sich einfach selbst ausdenkt), dann sollte man am Ende der Befragung auf die Seite des Anbieters umgeleitet werden und in der Adresszeile des Browsers sollte wieder die Test-Kennung stehen. Vermutlich zeigt der Anbieter dann eine Fehlermeldung, denn die Kennung ist ja nicht gültig.

**Tipp:** Mit der Funktion ''redirect()'' kann man die Teilnehmer natürlich auch wegschicken, wenn die Quote erfüllt ist. Ob die Quote schon erfüllt ist, kann man z.B. mithilfe der Funktion ''[[:de:create:functions:statistic|statistic()]]'' überprüfen.

**Wichtig:** Wenn ein Teilnehmer den Fragebogen mit ''redirect()'' verlässt, dann wird der Fragebogen im Datensatz __nicht__ als vollständig ausgefüllt markiert. Um unvollständige Datensätze zu filtern, muss man auf die letzte ausgefüllte Seite (LASTPAGE) zurückgreifen.

**Wichtig:** Wenn man den Platzhalter ''%reference%'' verwenden will, dann darf man mit ''[[:de:create:functions:replace|replace()]]'' __keinen__ Platzhalter auf diesen Namen vorbereiten.

===== Der Anbieter verwendet eine andere Variable als "r" =====

Falls der Anbieter im Link kein ''r'' verwenden kann oder will und auf eine Variable wie z.B. ''susid'' besteht, lässt sich das auch recht einfach lösen. Und zwar liest man die Variable dafür auf der ersten (!) Seite im Fragebogen mit einer Frage vom Typ [[:de:create:questions:client|Gerät und übermittelte Variablen]] ein. Tragen Sie den Namen der Variable ein, welche die Panel-Kennung enthält (z.B. "userID").

{{:de:survey:scr.panel.client.png?nolink|Frage vom Typ: Gerät und übermittelte Variablen}}

Als Platzhalter bei den Links muss man dann natürlich den Namen der Variable angeben, wie sie im Datensatz gespeichert wird. Wenn die Variable zum Einlesen z.B. ''DV01_RV1'' heißt, würde man den Platzhalter wie folgt setzen:

<code php>
// Dieser Code kann unter der Frage "Gerät und übermittelte Variablen"
// oder vor der Weiterleitung platziert werden
replace('%panelID%', 'DV01_RV1', 'response');  // Platzhalter vorbereiten
</code>

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

Anstatt mit ''replace()'' können Sie auch direkt mit ''value()'' und dem PHP-Operator zum verbinden von Strings (''.'') arbeiten. Der folgende PHP-Code führt zum selben Ergebnis wie die beiden PHP-Codes oben.

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


===== Panels und Zufallsauswahl =====

Eine normale [[:de:create:randomization]] hat auf die Panel-Anbindung keine Auswirkungen, aber wenn man mittels ''[[:de:create:functions:gotoquestionnaire]]'' eine [[:de:create:random_questionnaire]] realisiert, muss man die Panel-ID (und bei Bedarf weitere Variablen) an die untergeordneten Fragebögen übergeben.

Das Vorgehen wird hier im Detail beschrieben: [[:de:create:random_questionnaire#zusammenspiel_mit_externen_panels|Zusammenspiel mit externen Panels]]


===== Fehlersuche =====

Wenn Sie dem Panel-Anbieter den Fragebogen-Link (mit Platzhalter für die Panel-ID, siehe [[#link_mitteilen|Link mitteilen]] und [[#personalisierte_links_zum_fragebogen|Personalisierte Links zum Fragebogen]]) mitgeteilt haben, wird dieser Testen, ob die Redirects funktionieren.

Solle das nicht der Falls sein, kann das Problem an drei Stellen liegen:

  - Die Panel-ID wird vom Panel-Anbieter nicht korrekt an den Fragebogen übergeben
  - Die Panel-ID wird im Redirect nicht korrekt an den Panel-Anbieter zurückgegeben
  - Die ''redirect()''-Funktion wird aufgrund der Filterführung nicht aufgerufen

Um das Problem einzugrenzen, suchen Sie unter **Erhobene Daten** -> **Daten ansehen** zunächst die Test-Datensätze, welche der Panel-Anbieter erzeugt hat. Sollten Sie dort überhaupt keine passenden Fälle finden, prüfen Sie noch einmal, ob Sie dem Panel-Anbieter die Links zum korrekten Befragungsprojekt geschickt haben.

In den Datenfällen prüfen Sie nun, ob dort eine Panel-ID vorliegt. In aller Regel ist das eine lange Zahl oder ein kryptischer Code aus Ziffern und Buchstaben. Wenn Sie mit ''r='' arbeiten, sollte der Code in der Variable "REF" gespeichert werden. Wenn Sie den Code mit einer Frage "Gerät und übermittelte Variablen" einlesen, dann suchen Sie unter der Kennung dieser Frage. Wenn der Code nicht vorliegt, ...

  * haben Sie dem Panel-Anbieter entweder einen fehlerhaften Link zukommen lassen.
  * Oder in den **Projekt-Einstellungen** unter //Spezielles// wurde bei //Variablen im Link zum Fragebogen// für die Referenz ein anderer Variablenname festgelegt.
  * Oder die Frage "Gerät und übermittelte Variablen" wurde nicht auf der ersten Seite im Fragebogen platziert.
  * Oder Sie haben mehrere Fragebögen im Projekt definiert (**Fragebogen zusammenstellen** -> **Fragebögen verwalten**) und es wird der falsche davon aufgerufen.

Wenn die Panel-ID im Datensatz gespeichert wird, aber nicht zurück-übermittelt wird, prüfe Sie zunächst nochmal Ihre Redirect-Links und ob die Platzhalter dort richtig eingesetzt wurde.

**Tipp:** Zum Testen können Sie den Fragebogen einfach mit einer selbst gewählten Panel-ID starten. Wenn der Link also lautet ''%%https://s2survey.net/project/?r=[panelID]%%'', dann tragen Sie in der Adresszeile Ihres Browsers folgendes ein: ''%%https://s2survey.net/project/?r=Test0001%%''. Nach dem Redirect (so dieser funktioniert) erhalten Sie wahrscheinlich eine Fehlermeldung von der Website des Panel-Anbieters ... aber das ist in Ordnung, weil es in dessen Datenbank ja keine Panel-ID "Test0001" gibt. Sie sehen aber, ob die Panel-ID in der Adressezeile auftaucht.


===== Panel-Anbieter =====

Nachfolgend verlinken wir die uns bekannten Anleitungen von Panel-Anbietern.

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