Skip to content

Integrazione con il crowdsourcing

Esegui studi Potato su Prolific, SONA, CloudResearch Connect o qualsiasi panel che trasmetta un ID partecipante, con accesso tramite URL, codici di completamento e verifiche dell'attenzione.

Potato raccoglie annotazioni in crowdsourcing leggendo l'ID del partecipante dall'URL a cui la piattaforma indirizza le persone e mostrando un codice di completamento alla fine. Prolific, i subject pool SONA, CloudResearch Connect, Clickworker e Microworkers hanno ciascuno un provider, e il provider generic copre qualsiasi altro panel che funzioni allo stesso modo. Amazon Mechanical Turk ha chiuso il 30 settembre 2026, quindi uno studio che girava lì deve passare a una di queste piattaforme; la sezione «Spostare uno studio fuori da MTurk» più sotto elenca i passaggi.

Esecuzione su una porta aperta

Un worker deve poter raggiungere il server, quindi eseguilo su una porta aperta verso internet:

bash
potato start your-project -p 8080

I worker arrivano quindi a https://your-server:8080/. Metti davanti un reverse proxy per il TLS, come descritto in Configurazione di produzione.

Provider di crowdsourcing

Il blocco crowdsourcing indica la piattaforma. Prolific, SONA, Connect, Clickworker e Microworkers hanno provider dedicati, e generic gestisce qualsiasi panel che trasmetta un ID nell'URL e accetti un codice di completamento, come Besample, Positly, User Interviews, Testable Minds o 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 accetta i segnaposto {code}, {worker_id}, {session_id}, {study_id} e qualsiasi nome elencato in capture_params.

Ogni provider legge l'ID del partecipante dal parametro URL indicato da login.url_argument, quindi tieni login.type: url_direct accanto al blocco crowdsourcing e imposta url_argument sull'id_param del provider. È anche l'accesso url_direct a disattivare la richiesta della password. Una configurazione senza blocco crowdsourcing mantiene il comportamento precedente, in cui è solo l'accesso a leggere l'ID, e la configurazione minima di Prolific qui sotto lo usa.

Prolific

Configurazione minima

Bastano due impostazioni per eseguire uno studio su Prolific:

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

I worker che arrivano da Prolific accedono con il proprio PROLIFIC_PID senza che venga chiesta una password. Al termine vedono il codice di completamento e un pulsante per tornare a Prolific.

Il provider Prolific

Il provider prolific aggiunge un secondo codice per i partecipanti che non completano il task. Un partecipante bloccato dalle verifiche dell'attenzione, o che non supera la fase di addestramento, riceve failed_code al posto del codice di completamento:

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

L'URL dello studio

Nelle impostazioni del tuo studio su Prolific, imposta l'URL su:

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

Prolific sostituisce i valori reali. Potato registra SESSION_ID e STUDY_ID insieme all'ID del partecipante.

Reindirizzamento al completamento

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

Senza il reindirizzamento, la pagina finale mostra il codice, copiabile con un clic, e un pulsante di ritorno. È l'impostazione predefinita più sicura quando vuoi che i worker conservino il codice.

Integrazione con l'API di Prolific

Per studi più grandi Potato può comunicare con l'API di Prolific, il che gli permette di liberare i posti occupati da worker che hanno abbandonato o superato il tempo e di mettere in pausa lo studio quando il server è sovraccarico. Metti le credenziali in un file a parte:

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

Poi fai puntare la configurazione principale a quel file:

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

workload_checker è disattivato finché non lo attivi. Quando è attivo, Potato mette in pausa lo studio se i worker attivi superano max_concurrent_sessions e lo riprende quando scendono al 20% di quel numero, ma solo se è stato il monitor stesso a mettere in pausa lo studio. Uno studio che hai messo in pausa a mano non viene mai riavviato al posto tuo.

Recuperare il lavoro abbandonato

Quando un invio torna come RETURNED, TIMED-OUT o REJECTED, Potato libera gli item assegnati a quel worker e non ancora annotati, così che qualcun altro possa prenderli. Le annotazioni già completate vengono conservate. instance_reclaim modifica questo comportamento in base allo stato:

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

Subject pool SONA

SONA Systems gestisce i pool di partecipanti che molte università usano per assegnare crediti dei corsi. SONA inserisce nell'URL dello studio un codice univoco per ogni partecipante, e Potato usa quel codice come ID del partecipante:

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

In SONA, imposta l'URL dello studio su https://your-server.com/?sona_code=%SURVEY_CODE%. Quando un partecipante finisce, Potato assegna il credito da sé tramite la chiamata di accredito lato server di SONA, quindi il partecipante non deve seguire un link per tornare a SONA. Se quella chiamata non riesce, la pagina finale mostra invece il link di accredito lato client di SONA. Ogni assegnazione viene registrata nello stato del partecipante, quindi ricaricare la pagina finale non assegna mai il credito due volte.

CloudResearch Connect

Connect indirizza i partecipanti a uno studio esterno tramite il suo Project Link, con l'ID del partecipante in participantId e, facoltativamente, assignmentId e projectId. Potato li registra tutti e tre. Il completamento è un codice fisso, oppure un reindirizzamento all'URL di completamento indicato nelle impostazioni del progetto Connect:

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 non chiama l'API REST di Connect, quindi approvazioni e bonus si gestiscono in Connect.

Clickworker

Gli ordini di sondaggio esterno di Clickworker inviano i worker al tuo URL con il loro ID, e il completamento viene verificato rispetto a un codice che carichi su Clickworker:

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

Il provider può anche inviare una notifica di completamento che attiva il pagamento tramite l'API del marketplace di Clickworker. Quel postback è sperimentale, perché il suo contratto non è stato verificabile sulla documentazione pubblica, e resta disattivato a meno che la configurazione non imposti experimental: true accanto a un postback_url.

Microworkers

Le campagne Microworkers chiedono a ogni worker di incollare un codice di verifica, chiamato VCODE, per dimostrare di aver finito. Potato ricava il VCODE di ogni worker da un HMAC calcolato sugli ID del worker e della campagna, quindi lo stesso worker riceve sempre lo stesso codice, nessuno può indovinarne uno senza il segreto, e il metodo verify_vcode del provider ricalcola un codice per verificare un invio:

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

Imposta l'URL della campagna su Microworkers come https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}. Microworkers è una folla aperta di micro-task, quindi abbinala alle verifiche dell'attenzione e agli standard gold descritti più sotto.

Amazon Mechanical Turk (chiuso)

Amazon Mechanical Turk ha chiuso definitivamente il 30 settembre 2026 e non accetta più HIT né invia worker. Il provider mturk di Potato e l'accesso tramite workerId si caricano ancora, quindi una configurazione MTurk archiviata si avvia, ma nessun worker può raggiungerla. La pagina Integrazione MTurk conserva i dettagli per chi legge la configurazione di un vecchio studio.

Spostare uno studio fuori da MTurk

Gran parte della configurazione di uno studio MTurk resta invariata, perché verifiche dell'attenzione, standard gold, addestramento, assegnazione e quote funzionano allo stesso modo su ogni piattaforma. Il trasferimento richiede cinque passaggi:

  1. Scegli una piattaforma. Prolific e CloudResearch Connect reclutano popolazioni di ricerca generali, SONA serve il pool di un'università, e Clickworker e Microworkers sono folle aperte di micro-task che richiedono un controllo qualità più rigoroso.
  2. Cambia l'accesso. Mantieni login.type: url_direct e cambia login.url_argument da workerId al parametro ID della nuova piattaforma (PROLIFIC_PID, sona_code, participantId, worker_id o mw_id).
  3. Sostituisci i blocchi della piattaforma. Elimina il blocco mturk, perché Potato avvia ancora il suo client API MTurk finché quel blocco è presente, e aggiungi il blocco crowdsourcing della nuova piattaforma preso da questa pagina.
  4. Sostituisci l'HIT. Crea lo studio o il progetto sulla nuova piattaforma, fai puntare il suo URL esterno al tuo server con il segnaposto dell'ID della piattaforma nel link, e imposta il codice di completamento o il reindirizzamento che ti fornisce.
  5. Mantieni i controlli di qualità. Lascia attention_checks, gold_standards e la fase di addestramento come erano, così i risultati restano confrontabili con i dati MTurk.

Controllo qualità

Verifiche dell'attenzione

Item con risposte note, mescolati nella coda:

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 intercetta il tipo di errore a cui il crowdsourcing è più esposto, cioè cliccare più in fretta di quanto chiunque possa leggere l'item.

Standard gold

Gli item etichettati da esperti misurano l'accuratezza e non l'attenzione, e per impostazione predefinita restano silenziosi, così i worker non ricevono alcun riscontro che insegni loro le risposte:

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

Consulta Controllo qualità per i formati degli item e per come vengono riportati entrambi.

Pagine di completamento personalizzate

La pagina di completamento integrata gestisce un codice e un pulsante di ritorno. Se ti serve di più, concludi lo studio con una pagina surveyflow:

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

La pagina finale è un item pure_display che contiene il link o il testo che ti serve:

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>"]}

Esempio completo: studio Prolific

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

Monitoraggio dello studio

La dashboard di amministrazione su /admin riporta i tassi di completamento, il tempo per istanza e i risultati delle verifiche dell'attenzione mentre lo studio è in corso. Per accedervi serve la chiave condivisa admin_api_key oppure un ruolo che includa view_admin_dashboard:

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

Esporta le annotazioni raccolte con la CLI di esportazione:

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

Buone pratiche

  1. Parti da un pilota: prova con pochi worker prima di lanciare su larga scala
  2. Paga in modo equo: cronometra tu stesso il task e fissa il compenso in base alla durata reale
  3. Scrivi istruzioni chiare: includi esempi e i casi limite che ti aspetti
  4. Usa le verifiche dell'attenzione: individua presto chi clicca senza leggere, non in fase di analisi
  5. Aggiungi standard gold: attenzione e accuratezza sono misure diverse
  6. Tieni d'occhio la dashboard: i problemi costano poco da risolvere il primo giorno e molto il quinto
  7. Decidi prima i criteri di rifiuto: i worker devono conoscere lo standard prima di iniziare
  8. Esporta regolarmente: non aspettare la chiusura dello studio

Ulteriori letture

Per i dettagli di implementazione, consulta la documentazione sorgente, il riferimento Prolific e la panoramica delle piattaforme.