Crowdsourcing-Integration

Führen Sie Potato-Studien auf Prolific, SONA, CloudResearch Connect oder jedem Panel durch, das eine Teilnehmer-ID übergibt, mit Login über die URL, Abschlusscodes und Aufmerksamkeitsprüfungen.

Potato sammelt Crowdsourcing-Annotationen, indem es die Teilnehmer-ID aus der URL liest, über die die Plattform die Teilnehmenden weiterleitet, und am Ende einen Abschlusscode anzeigt. Prolific, SONA-Teilnehmerpools, CloudResearch Connect, Clickworker und Microworkers haben jeweils einen eigenen Anbieter, und der Anbieter generic deckt jedes andere Panel ab, das auf dieselbe Weise arbeitet. Amazon Mechanical Turk wurde am 30. September 2026 geschlossen. Eine Studie, die dort lief, muss deshalb auf eine dieser Plattformen umziehen, und der Abschnitt „Eine Studie von MTurk umziehen“ weiter unten führt die Schritte auf.

Betrieb auf einem offenen Port

Ein Crowd-Worker muss den Server erreichen können, also betreiben Sie ihn auf einem Port, der zum Internet hin offen ist:

bash

potato start your-project -p 8080

Die Worker gelangen dann zu https://your-server:8080/. Schalten Sie für TLS einen Reverse Proxy davor, wie in Produktionseinrichtung beschrieben.

Crowd-Anbieter

Der Block crowdsourcing benennt die Plattform. Prolific, SONA, Connect, Clickworker und Microworkers haben eigene Anbieter, und generic bedient jedes Panel, das eine ID in der URL übergibt und einen Abschlusscode akzeptiert, etwa Besample, Positly, User Interviews, Testable Minds oder Cint:

yaml

login:
  type: url_direct
  url_argument: response_id        # must match id_param below
 
crowdsourcing:
  provider: generic                # or prolific, sona, connect, clickworker, microworkers
  generic:
    platform_label: "Besample"     # shown on the done-page return button
    id_param: response_id          # URL parameter carrying the participant ID
    capture_params: [study]        # extra URL params to record
    completion:
      code: "BSMP-4432"
      redirect_url: "https://besample.app/complete?rid={worker_id}&code={code}"
      failed_code: "BSMP-FAIL"     # optional, for blocked participants

redirect_url akzeptiert die Platzhalter {code}, {worker_id}, {session_id}, {study_id} sowie jeden in capture_params aufgeführten Namen.

Jeder Anbieter liest die Teilnehmer-ID aus dem URL-Parameter, den login.url_argument benennt. Behalten Sie also login.type: url_direct neben dem Block crowdsourcing bei und setzen Sie url_argument auf den id_param des Anbieters. Der Login url_direct ist auch das, was die Passwortabfrage abschaltet. Eine Konfiguration ohne crowdsourcing-Block behält das ältere Verhalten bei, bei dem allein der Login die ID liest, und die minimale Prolific-Einrichtung weiter unten nutzt genau das.

Prolific

Minimale Einrichtung

Zwei Einstellungen genügen für eine Prolific-Studie:

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID   # the default
 
completion_code: "YOUR-PROLIFIC-CODE"

Worker, die von Prolific kommen, werden unter ihrer PROLIFIC_PID ohne Passwortabfrage angemeldet. Wenn sie fertig sind, sehen sie den Abschlusscode und eine Schaltfläche zurück zu Prolific.

Der Prolific-Anbieter

Der Anbieter prolific fügt einen zweiten Code für Teilnehmende hinzu, die die Aufgabe nicht abschließen. Wer durch die Aufmerksamkeitsprüfungen gesperrt wird oder die Trainingsphase nicht besteht, erhält failed_code statt des Abschlusscodes:

yaml

login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
crowdsourcing:
  provider: prolific
  prolific:
    completion:
      code: "C1ABCDEF"          # defaults to the top-level completion_code
      failed_code: "C1FAILED"   # optional

Die Studien-URL

Setzen Sie in den Einstellungen Ihrer Prolific-Studie die URL auf:

text

https://your-server:8080/?PROLIFIC_PID={{%PROLIFIC_PID%}}&SESSION_ID={{%SESSION_ID%}}&STUDY_ID={{%STUDY_ID%}}

Prolific setzt die echten Werte ein. Potato speichert SESSION_ID und STUDY_ID zusammen mit der Teilnehmer-ID.

Weiterleitung nach Abschluss

yaml

completion_code: "YOUR-PROLIFIC-CODE"
auto_redirect_on_completion: true
auto_redirect_delay: 5000   # milliseconds

Ohne die Weiterleitung zeigt die Abschlussseite den Code mit Kopieren per Klick und eine Zurück-Schaltfläche an. Das ist die sicherere Voreinstellung, wenn die Worker den Code festhalten sollen.

Integration der Prolific-API

Bei größeren Studien kann Potato mit der Prolific-API kommunizieren. Damit kann es Plätze freigeben, die von zurückgetretenen oder abgelaufenen Workern belegt sind, und die Studie pausieren, wenn der Server ausgelastet ist. Legen Sie die Zugangsdaten in eine eigene Datei:

yaml

# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
max_concurrent_sessions: 30
workload_checker: true
workload_checker_period: 300

Verweisen Sie dann in der Hauptkonfiguration darauf:

yaml

login:
  type: prolific
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "YOUR-PROLIFIC-CODE"

workload_checker ist ausgeschaltet, solange Sie ihn nicht einschalten. Ist er eingeschaltet, pausiert Potato die Studie, wenn die Zahl aktiver Worker max_concurrent_sessions übersteigt, und setzt sie fort, wenn sie auf 20 % dieses Werts sinkt, allerdings nur, wenn der Monitor die Studie selbst pausiert hat. Eine Studie, die Sie von Hand pausiert haben, wird nie für Sie neu gestartet.

Abgebrochene Arbeit zurückholen

Wenn eine Einreichung mit RETURNED, TIMED-OUT oder REJECTED zurückkommt, gibt Potato die Items frei, die diesem Worker zugewiesen, aber noch nicht annotiert sind, damit jemand anderes sie übernehmen kann. Bereits abgeschlossene Annotationen bleiben erhalten. instance_reclaim ändert dieses Verhalten je nach Status:

yaml

instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

SONA-Teilnehmerpools

SONA Systems betreibt die Teilnehmerpools, über die viele Universitäten Studienleistungen als Kurs-Credits vergeben. SONA fügt für jede teilnehmende Person einen eindeutigen Code in die Studien-URL ein, und Potato verwendet diesen Code als Teilnehmer-ID:

yaml

login:
  type: url_direct
  url_argument: sona_code
 
crowdsourcing:
  provider: sona
  sona:
    hostname: yourdept.sona-systems.com
    experiment_id: 123
    credit_token: your-credit-token   # both from the client-side completion URL on SONA's study information page
    id_param: sona_code               # the default; must match login.url_argument

Setzen Sie in SONA die Studien-URL auf https://your-server.com/?sona_code=%SURVEY_CODE%. Wenn eine teilnehmende Person fertig ist, vergibt Potato den Credit selbst über den serverseitigen Credit-Aufruf von SONA, sodass die Person keinem Link zurück zu SONA folgen muss. Schlägt dieser Aufruf fehl, zeigt die Abschlussseite stattdessen den clientseitigen Credit-Link von SONA an. Jede Vergabe wird im Zustand der teilnehmenden Person gespeichert, sodass ein Neuladen der Abschlussseite den Credit nie doppelt vergibt.

CloudResearch Connect

Connect schickt Teilnehmende über seinen Project Link zu einer externen Studie, mit der ID der Person in participantId und optional assignmentId und projectId. Potato speichert alle drei. Der Abschluss erfolgt über einen festen Code oder über eine Weiterleitung zu der Abschluss-URL, die in den Einstellungen des Connect-Projekts angezeigt wird:

yaml

login:
  type: url_direct
  url_argument: participantId
 
crowdsourcing:
  provider: connect
  connect:
    completion:
      code: "ABC123"
      # or: redirect_url: "https://connect.cloudresearch.com/participant/project/<id>/complete"

Potato ruft die REST-API von Connect nicht auf, daher erfolgen Genehmigungen und Boni in Connect.

Clickworker

Die Aufträge für externe Umfragen bei Clickworker schicken Worker mit ihrer ID an Ihre URL, und der Abschluss wird anhand eines Codes geprüft, den Sie bei Clickworker hochladen:

yaml

login:
  type: url_direct
  url_argument: worker_id
 
crowdsourcing:
  provider: clickworker
  clickworker:
    id_param: worker_id      # the default
    completion:
      code: "CW-DONE-01"

Der Anbieter kann außerdem eine Abschlussbenachrichtigung senden, die die Bezahlung über die Marktplatz-API von Clickworker auslöst. Dieses Postback ist experimentell, weil sich seine Schnittstelle nicht anhand öffentlicher Dokumentation prüfen ließ, und es bleibt ausgeschaltet, solange die Konfiguration nicht experimental: true neben einer postback_url setzt.

Microworkers

Kampagnen auf Microworkers verlangen von jedem Worker, einen Verifizierungscode, den sogenannten VCODE, zurückzugeben, um den Abschluss zu belegen. Potato leitet den VCODE jedes Workers aus einem HMAC über die Worker- und die Kampagnen-ID ab. Derselbe Worker erhält also immer denselben Code, niemand kann ohne das Geheimnis einen Code erraten, und die Methode verify_vcode des Anbieters berechnet einen Code neu, um eine Einreichung zu prüfen:

yaml

login:
  type: url_direct
  url_argument: mw_id
 
crowdsourcing:
  provider: microworkers
  microworkers:
    id_param: mw_id                        # matches {{MW_ID}} in the campaign URL
    capture_params: [campaign_id, slot_id]
    vcode_secret: "keep-this-private"
    vcode_prefix: "mw-"                    # optional

Setzen Sie die Kampagnen-URL auf Microworkers auf https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}. Microworkers ist eine offene Mikrotask-Crowd, kombinieren Sie es daher mit den Aufmerksamkeitsprüfungen und Goldstandards weiter unten.

Amazon Mechanical Turk (geschlossen)

Amazon Mechanical Turk wurde am 30. September 2026 endgültig geschlossen und nimmt keine HITs mehr an und schickt keine Worker mehr. Der Anbieter mturk von Potato und der Login über workerId lassen sich weiterhin laden, sodass eine archivierte MTurk-Konfiguration startet, aber kein Worker kann sie erreichen. Die Seite MTurk-Integration bewahrt die Details für alle auf, die die Konfiguration einer alten Studie lesen.

Eine Studie von MTurk umziehen

Der größte Teil der Konfiguration einer MTurk-Studie lässt sich unverändert übernehmen, weil Aufmerksamkeitsprüfungen, Goldstandards, Training, Zuweisung und Kontingente auf jeder Plattform gleich funktionieren. Fünf Schritte genügen für den Umzug:

Eine Plattform wählen. Prolific und CloudResearch Connect rekrutieren allgemeine Forschungspopulationen, SONA bedient den eigenen Pool einer Universität, und Clickworker und Microworkers sind offene Mikrotask-Crowds, die eine strengere Qualitätskontrolle brauchen.
Den Login ändern. Behalten Sie login.type: url_direct bei und ändern Sie login.url_argument von workerId auf den ID-Parameter der neuen Plattform (PROLIFIC_PID, sona_code, participantId, worker_id oder mw_id).
Die Plattform-Blöcke austauschen. Löschen Sie den Block mturk, weil Potato seinen MTurk-API-Client weiterhin startet, solange dieser Block vorhanden ist, und fügen Sie den crowdsourcing-Block der neuen Plattform von dieser Seite hinzu.
Den HIT ersetzen. Legen Sie die Studie oder das Projekt auf der neuen Plattform an, lassen Sie deren externe URL mit dem ID-Platzhalter der Plattform im Link auf Ihren Server zeigen, und setzen Sie den Abschlusscode oder die Weiterleitung, die die Plattform Ihnen gibt.
Die Qualitätskontrollen beibehalten. Lassen Sie attention_checks, gold_standards und die Trainingsphase unverändert, damit die Ergebnisse mit den MTurk-Daten vergleichbar bleiben.

Qualitätskontrolle

Aufmerksamkeitsprüfungen

Items mit bekannten Antworten, in die Warteschlange eingestreut:

yaml

attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    warn_message: "Please read items carefully before answering."
    block_threshold: 5
    block_message: "You have been blocked due to too many incorrect responses."

min_response_time erkennt den Fehlermodus, dem Crowdsourcing am stärksten ausgesetzt ist, nämlich schnelleres Durchklicken, als irgendjemand das Item lesen könnte.

Goldstandards

Von Fachleuten gelabelte Items messen Genauigkeit statt Aufmerksamkeit, und sie bleiben standardmäßig stumm, damit die Worker kein Feedback erhalten, das ihnen die Antworten beibringt:

yaml

gold_standards:
  enabled: true
  items_file: data/gold_standards.json
  mode: mixed
  frequency: 20
  accuracy:
    min_threshold: 0.7
    evaluation_count: 5

Unter Qualitätskontrolle finden Sie die Item-Formate und wie beide ausgewertet werden.

Eigene Abschlussseiten

Die eingebaute Abschlussseite bietet einen Code und eine Zurück-Schaltfläche. Wenn Sie mehr brauchen, beenden Sie die Studie stattdessen mit einer Surveyflow-Seite:

yaml

surveyflow:
  on: true
  order:
    - pre_annotation
    - post_annotation
  pre_annotation:
    - surveyflow/consent.jsonl
  post_annotation:
    - surveyflow/end.jsonl

Die Abschlussseite ist ein pure_display-Item mit dem Link oder Text, den Sie benötigen:

json

{"id":"1","text":"Thanks for participating. Click below to complete the study.","schema":"pure_display","choices":["<a href=\"https://app.prolific.com/submissions/complete?cc=YOUR-CODE\" target=\"_blank\">Complete Study on Prolific</a>"]}

Vollständiges Beispiel: Prolific-Studie

yaml

annotation_task_name: "Sentiment Analysis Study"
task_dir: .
 
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
completion_code: "SENT2024"
auto_redirect_on_completion: false
 
hide_navbar: true
jumping_to_id_disabled: true
 
user_config:
  allow_all_users: true
 
assignment_strategy: random
max_annotations_per_user: 50
num_annotators_per_item: 3
 
phases:
  order:
    - consent
    - instructions
    - annotation
  consent:
    file: data/consent.html
  instructions:
    file: data/instructions.html
  annotation:
    type: annotation
 
attention_checks:
  enabled: true
  items_file: data/attention_checks.json
  frequency: 10
  failure_handling:
    warn_threshold: 2
    block_threshold: 5
 
data_files:
  - data/main.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels:
      - Positive
      - Negative
      - Neutral
    sequential_key_binding: true
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

Die Studie überwachen

Das Admin-Dashboard unter /admin zeigt während der Studie Abschlussraten, Zeit pro Instanz und die Ergebnisse der Aufmerksamkeitsprüfungen. Für den Zugriff braucht man entweder den gemeinsamen admin_api_key oder eine Rolle mit view_admin_dashboard:

yaml

admin_api_key: "your-shared-key"
 
rbac:
  enabled: true
  user_role_assignments:
    researcher@university.edu: admin

Exportieren Sie die gesammelten Annotationen mit der Export-CLI:

bash

python -m potato.export -c config.yaml -f csv -o ./export/

Bewährte Methoden

Zuerst ein Pilot: Testen Sie mit wenigen Workern, bevor Sie im großen Maßstab starten
Fair bezahlen: Messen Sie die Dauer der Aufgabe selbst und kalkulieren Sie den Preis nach der tatsächlichen Dauer
Klare Anweisungen schreiben: Nehmen Sie Beispiele und die erwarteten Grenzfälle auf
Aufmerksamkeitsprüfungen verwenden: Erkennen Sie Durchklicken früh statt erst bei der Analyse
Goldstandards hinzufügen: Aufmerksamkeit und Genauigkeit sind unterschiedliche Messgrößen
Das Dashboard beobachten: Probleme sind am ersten Tag billig zu beheben und am fünften teuer
Ablehnungskriterien vorab festlegen: Worker sollten den Maßstab kennen, bevor sie anfangen
Regelmäßig exportieren: Warten Sie nicht, bis die Studie endet

Weiterführende Informationen

Eine Crowdsourcing-Studie durchführen: Rekrutierung, Bezahlung und Qualitätskontrolle
MTurk-Integration: Was sich mit der Schließung von MTurk geändert hat
Passwortloser Login: URL-basierte Authentifizierung
Qualitätskontrolle: Aufmerksamkeitsprüfungen und Goldstandards
Benutzerverwaltung: Zugriffslisten, Rollen und Kontingente

Implementierungsdetails finden Sie in der Quelldokumentation, der Prolific-Referenz und der Plattformübersicht.