Skip to content

Intégration du crowdsourcing

Menez des études Potato sur Prolific, SONA, CloudResearch Connect ou tout panel qui transmet un identifiant de participant, avec connexion par URL, codes de finalisation et vérifications d'attention.

Potato recueille des annotations en crowdsourcing en lisant l'identifiant du participant dans l'URL vers laquelle la plateforme envoie les personnes, puis en affichant un code de finalisation à la fin. Prolific, les viviers de participants SONA, CloudResearch Connect, Clickworker et Microworkers ont chacun leur fournisseur, et le fournisseur generic couvre tout autre panel qui fonctionne de la même manière. Amazon Mechanical Turk a fermé le 30 septembre 2026 : une étude qui y tournait doit donc passer sur l'une de ces plateformes, et la section « Faire migrer une étude hors de MTurk », plus bas, en donne les étapes.

Exécution sur un port ouvert

Un travailleur doit pouvoir atteindre le serveur, il faut donc l'exécuter sur un port ouvert à Internet :

bash
potato start your-project -p 8080

Les travailleurs arrivent alors sur https://your-server:8080/. Placez un proxy inverse devant le serveur pour le TLS, comme décrit dans Configuration de production.

Fournisseurs de crowdsourcing

Le bloc crowdsourcing désigne la plateforme. Prolific, SONA, Connect, Clickworker et Microworkers ont des fournisseurs dédiés, et generic prend en charge tout panel qui transmet un identifiant dans l'URL et accepte un code de finalisation, comme Besample, Positly, User Interviews, Testable Minds ou 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 accepte les espaces réservés {code}, {worker_id}, {session_id}, {study_id} ainsi que tout nom listé dans capture_params.

Chaque fournisseur lit l'identifiant du participant dans le paramètre d'URL nommé par login.url_argument : gardez donc login.type: url_direct à côté du bloc crowdsourcing et réglez url_argument sur le id_param du fournisseur. C'est aussi la connexion url_direct qui supprime la demande de mot de passe. Une configuration sans bloc crowdsourcing conserve l'ancien comportement, dans lequel la connexion seule lit l'identifiant, et la configuration minimale de Prolific ci-dessous l'utilise.

Prolific

Configuration minimale

Deux paramètres suffisent pour mener une étude Prolific :

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

Les travailleurs qui arrivent de Prolific sont connectés sous leur PROLIFIC_PID sans qu'on leur demande de mot de passe. À la fin, ils voient le code de finalisation et un bouton de retour vers Prolific.

Le fournisseur Prolific

Le fournisseur prolific ajoute un second code pour les participants qui ne terminent pas la tâche. Un participant bloqué par les vérifications d'attention, ou qui échoue à la phase d'entraînement, reçoit failed_code au lieu du code de finalisation :

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 de l'étude

Dans les paramètres de votre étude Prolific, définissez l'URL comme suit :

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

Prolific remplace ces variables par les vraies valeurs. Potato enregistre SESSION_ID et STUDY_ID avec l'identifiant du participant.

Redirection à la fin

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

Sans la redirection, la page finale affiche le code, copiable d'un clic, et un bouton de retour. C'est le choix par défaut le plus sûr si vous voulez que les travailleurs gardent une trace du code.

Intégration de l'API Prolific

Pour les études plus importantes, Potato peut dialoguer avec l'API Prolific, ce qui lui permet de libérer les places occupées par des travailleurs qui ont abandonné ou dépassé le temps imparti, et de mettre l'étude en pause quand le serveur est surchargé. Placez les identifiants dans un fichier à part :

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

Faites ensuite pointer la configuration principale vers ce fichier :

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

workload_checker est désactivé tant que vous ne l'activez pas. Une fois activé, Potato met l'étude en pause quand le nombre de travailleurs actifs dépasse max_concurrent_sessions et la relance quand il redescend à 20 % de ce nombre, mais seulement si c'est le moniteur lui-même qui a mis l'étude en pause. Une étude que vous avez mise en pause à la main n'est jamais relancée à votre place.

Récupérer le travail abandonné

Quand une soumission revient avec le statut RETURNED, TIMED-OUT ou REJECTED, Potato libère les items attribués à ce travailleur et pas encore annotés, pour que quelqu'un d'autre puisse les prendre. Les annotations déjà terminées sont conservées. instance_reclaim modifie ce comportement selon le statut :

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

Viviers de participants SONA

SONA Systems gère les viviers de participants que de nombreuses universités utilisent pour attribuer des crédits de cours. SONA place dans l'URL de l'étude un code unique pour chaque participant, et Potato utilise ce code comme identifiant du participant :

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

Dans SONA, définissez l'URL de l'étude sur https://your-server.com/?sona_code=%SURVEY_CODE%. Quand un participant termine, Potato attribue lui-même le crédit par l'appel de crédit côté serveur de SONA, si bien que le participant n'a pas à suivre de lien pour revenir sur SONA. Si cet appel échoue, la page finale affiche à la place le lien de crédit côté client de SONA. Chaque attribution est enregistrée dans l'état du participant, si bien que recharger la page finale n'attribue jamais le crédit deux fois.

CloudResearch Connect

Connect envoie les participants vers une étude externe par son Project Link, avec l'identifiant du participant dans participantId et, en option, assignmentId et projectId. Potato enregistre les trois. La finalisation passe par un code fixe ou par une redirection vers l'URL de finalisation affichée dans les paramètres du projet 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 n'appelle pas l'API REST de Connect : les validations et les primes se font donc dans Connect.

Clickworker

Les commandes d'enquêtes externes de Clickworker envoient les travailleurs vers votre URL avec leur identifiant, et la finalisation est vérifiée au moyen d'un code que vous téléversez sur 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"

Le fournisseur peut aussi envoyer une notification de finalisation qui déclenche le paiement par l'API de la place de marché de Clickworker. Ce postback est expérimental, car son contrat n'a pas pu être vérifié dans une documentation publique, et il reste désactivé tant que la configuration ne définit pas experimental: true à côté d'une postback_url.

Microworkers

Les campagnes Microworkers demandent à chaque travailleur de renvoyer un code de vérification, appelé VCODE, pour prouver qu'il a terminé. Potato dérive le VCODE de chaque travailleur d'un HMAC calculé sur les identifiants du travailleur et de la campagne : le même travailleur reçoit donc toujours le même code, personne ne peut en deviner un sans le secret, et la méthode verify_vcode du fournisseur recalcule un code pour vérifier une soumission :

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

Définissez l'URL de la campagne sur Microworkers comme https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}. Microworkers est une foule ouverte de microtâches : associez-le donc aux vérifications d'attention et aux standards de référence décrits plus bas.

Amazon Mechanical Turk (fermé)

Amazon Mechanical Turk a fermé définitivement le 30 septembre 2026 et n'accepte plus de HIT ni n'envoie de travailleurs. Le fournisseur mturk de Potato et la connexion par workerId se chargent toujours, si bien qu'une configuration MTurk archivée démarre, mais aucun travailleur ne peut l'atteindre. La page Intégration avec MTurk conserve les détails pour qui lit la configuration d'une ancienne étude.

Faire migrer une étude hors de MTurk

L'essentiel de la configuration d'une étude MTurk se reprend sans modification, car les vérifications d'attention, les standards de référence, l'entraînement, l'attribution et les quotas fonctionnent de la même façon sur toutes les plateformes. La migration se fait en cinq étapes :

  1. Choisissez une plateforme. Prolific et CloudResearch Connect recrutent des populations de recherche générales, SONA dessert le vivier propre à une université, et Clickworker et Microworkers sont des foules ouvertes de microtâches qui demandent un contrôle de la qualité plus strict.
  2. Modifiez la connexion. Gardez login.type: url_direct et remplacez, dans login.url_argument, workerId par le paramètre d'identifiant de la nouvelle plateforme (PROLIFIC_PID, sona_code, participantId, worker_id ou mw_id).
  3. Remplacez les blocs de plateforme. Supprimez le bloc mturk, car Potato démarre encore son client de l'API MTurk tant que ce bloc est présent, et ajoutez le bloc crowdsourcing de la nouvelle plateforme donné sur cette page.
  4. Remplacez le HIT. Créez l'étude ou le projet sur la nouvelle plateforme, faites pointer son URL externe vers votre serveur avec l'espace réservé d'identifiant de la plateforme dans le lien, et définissez le code de finalisation ou la redirection qu'elle vous fournit.
  5. Conservez les contrôles de qualité. Laissez attention_checks, gold_standards et la phase d'entraînement tels quels, pour que les résultats restent comparables aux données MTurk.

Contrôle de la qualité

Vérifications d'attention

Des items dont la réponse est connue, mélangés à la file :

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 repère le mode d'échec auquel le crowdsourcing est le plus exposé, qui consiste à cliquer plus vite que quiconque ne pourrait lire l'item.

Standards de référence

Les items étiquetés par des experts mesurent l'exactitude plutôt que l'attention, et ils restent silencieux par défaut, pour que les travailleurs ne reçoivent aucun retour qui leur apprendrait les réponses :

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

Consultez Contrôle de la qualité pour les formats des items et la manière dont les deux mécanismes sont rapportés.

Pages de finalisation personnalisées

La page de finalisation intégrée gère un code et un bouton de retour. S'il vous faut davantage, terminez plutôt l'étude par une page surveyflow :

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

La page finale est un item pure_display qui porte le lien ou le texte dont vous avez besoin :

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

Exemple complet : étude 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

Suivi de l'étude

Le tableau de bord d'administration, à l'adresse /admin, présente les taux de finalisation, le temps par instance et les résultats des vérifications d'attention pendant que l'étude se déroule. Pour y accéder, il faut soit la clé partagée admin_api_key, soit un rôle doté de view_admin_dashboard :

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

Exportez les annotations recueillies avec la CLI d'export :

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

Bonnes pratiques

  1. Commencez par un pilote : lancez l'étude avec une poignée de travailleurs avant de passer à grande échelle
  2. Rémunérez équitablement : chronométrez la tâche vous-même et fixez le prix d'après sa durée réelle
  3. Rédigez des consignes claires : incluez des exemples et les cas limites que vous prévoyez
  4. Utilisez des vérifications d'attention : repérez les clics à la chaîne tôt plutôt qu'au moment de l'analyse
  5. Ajoutez des standards de référence : l'attention et l'exactitude sont deux mesures différentes
  6. Surveillez le tableau de bord : un problème coûte peu à corriger le premier jour et cher le cinquième
  7. Fixez les critères de rejet à l'avance : les travailleurs doivent connaître la règle avant de commencer
  8. Exportez régulièrement : n'attendez pas la clôture de l'étude

Pour aller plus loin

Pour les détails d'implémentation, consultez la documentation source, la référence Prolific et le panorama des plateformes.