Integración de crowdsourcing

Ejecuta estudios de Potato en Prolific, SONA, CloudResearch Connect o cualquier panel que pase un ID de participante, con inicio de sesión por URL, códigos de finalización y verificaciones de atención.

Potato recoge anotaciones de crowdsourcing leyendo el ID del participante de la URL a la que la plataforma envía a las personas y mostrando un código de finalización al terminar. Prolific, los grupos de participantes de SONA, CloudResearch Connect, Clickworker y Microworkers tienen cada uno su proveedor, y el proveedor generic cubre cualquier otro panel que funcione de la misma manera. Amazon Mechanical Turk cerró el 30 de septiembre de 2026, así que un estudio que se ejecutaba allí tiene que pasar a una de estas plataformas, y la sección «Trasladar un estudio fuera de MTurk», más abajo, enumera los pasos.

Ejecución en un puerto abierto

Un trabajador de la plataforma tiene que poder llegar al servidor, así que ejecútalo en un puerto abierto a internet:

bash

potato start your-project -p 8080

Los trabajadores llegan entonces a https://your-server:8080/. Coloca delante un proxy inverso para TLS, como se describe en Configuración de producción.

Proveedores de crowdsourcing

El bloque crowdsourcing indica la plataforma. Prolific, SONA, Connect, Clickworker y Microworkers tienen proveedores propios, y generic sirve para cualquier panel que pase un ID en la URL y acepte un código de finalización, como 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 acepta los marcadores {code}, {worker_id}, {session_id}, {study_id} y cualquier nombre incluido en capture_params.

Todos los proveedores leen el ID del participante del parámetro de URL que indica login.url_argument, así que mantén login.type: url_direct junto al bloque crowdsourcing y ajusta url_argument al id_param del proveedor. El inicio de sesión url_direct es también lo que desactiva la petición de contraseña. Una configuración sin bloque crowdsourcing conserva el comportamiento anterior, en el que solo el inicio de sesión lee el ID, y la configuración mínima de Prolific que aparece más abajo lo utiliza.

Prolific

Configuración mínima

Dos ajustes bastan para ejecutar un estudio en Prolific:

yaml

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

Los trabajadores que llegan desde Prolific inician sesión con su PROLIFIC_PID sin que se les pida contraseña. Al terminar, ven el código de finalización y un botón para volver a Prolific.

El proveedor de Prolific

El proveedor prolific añade un segundo código para los participantes que no completan la tarea. Un participante bloqueado por las verificaciones de atención, o que no supera la fase de entrenamiento, recibe failed_code en lugar del código de finalización:

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

La URL del estudio

En la configuración de tu estudio en Prolific, establece la URL como:

text

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

Prolific sustituye los valores reales. Potato registra SESSION_ID y STUDY_ID junto con el ID del participante.

Redirección al finalizar

yaml

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

Sin la redirección, la página final muestra el código con copia al hacer clic y un botón de retorno, que es la opción predeterminada más segura cuando quieres que los trabajadores guarden constancia del código.

Integración con la API de Prolific

En estudios más grandes, Potato puede comunicarse con la API de Prolific, lo que le permite liberar los puestos ocupados por trabajadores que abandonaron o agotaron el tiempo y pausar el estudio cuando el servidor está saturado. Pon las credenciales en un archivo aparte:

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

Después, apunta la configuración principal a ese archivo:

yaml

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

workload_checker está desactivado salvo que lo actives. Con él activado, Potato pausa el estudio cuando los trabajadores activos superan max_concurrent_sessions y lo reanuda cuando bajan al 20% de ese número, aunque solo si fue el propio monitor quien pausó el estudio. Un estudio que pausaste a mano nunca se reinicia por ti.

Recuperar trabajo abandonado

Cuando un envío vuelve como RETURNED, TIMED-OUT o REJECTED, Potato libera los ítems asignados a ese trabajador que aún no están anotados, para que otra persona pueda tomarlos. Las anotaciones que ya completó se conservan. instance_reclaim cambia ese comportamiento según el estado:

yaml

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

Grupos de participantes de SONA

SONA Systems gestiona los grupos de participantes que muchas universidades usan para otorgar créditos de curso. SONA incluye en la URL del estudio un código único para cada participante, y Potato usa ese código como ID del participante:

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

En SONA, establece la URL del estudio como https://your-server.com/?sona_code=%SURVEY_CODE%. Cuando un participante termina, Potato otorga el crédito por sí mismo mediante la llamada de crédito del lado del servidor de SONA, de modo que el participante no tiene que seguir ningún enlace de vuelta a SONA. Si esa llamada falla, la página final muestra en su lugar el enlace de crédito del lado del cliente de SONA. Cada concesión queda registrada en el estado del participante, así que recargar la página final nunca otorga el crédito dos veces.

CloudResearch Connect

Connect envía a los participantes a un estudio externo mediante su Project Link, con el ID del participante en participantId y, opcionalmente, assignmentId y projectId. Potato registra los tres. La finalización es un código fijo o una redirección a la URL de finalización que aparece en la configuración del proyecto de 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 no llama a la API REST de Connect, así que las aprobaciones y las bonificaciones se gestionan en Connect.

Clickworker

Los pedidos de encuestas externas de Clickworker envían a los trabajadores a tu URL con su ID, y la finalización se comprueba con un código que subes a 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"

El proveedor también puede enviar una notificación de finalización que desencadena el pago a través de la API del marketplace de Clickworker. Ese postback es experimental, porque su contrato no se pudo verificar con documentación pública, y permanece desactivado salvo que la configuración establezca experimental: true junto a una postback_url.

Microworkers

Las campañas de Microworkers piden a cada trabajador que devuelva un código de verificación, llamado VCODE, para demostrar que terminó. Potato obtiene el VCODE de cada trabajador a partir de un HMAC sobre los ID del trabajador y de la campaña, de modo que el mismo trabajador siempre recibe el mismo código, nadie puede adivinar uno sin el secreto, y el método verify_vcode del proveedor vuelve a calcular un código para comprobar un envío:

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

Establece la URL de la campaña en Microworkers como https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}. Microworkers es una comunidad abierta de microtareas, así que combínalo con las verificaciones de atención y los estándares de oro que se describen más abajo.

Amazon Mechanical Turk (cerrado)

Amazon Mechanical Turk cerró definitivamente el 30 de septiembre de 2026 y ya no acepta HIT ni envía trabajadores. El proveedor mturk de Potato y el inicio de sesión con workerId siguen cargando, así que una configuración archivada de MTurk arranca, pero ningún trabajador puede llegar a ella. La página Integración con MTurk conserva los detalles para quien lea la configuración de un estudio antiguo.

Trasladar un estudio fuera de MTurk

La mayor parte de la configuración de un estudio de MTurk se mantiene sin cambios, porque las verificaciones de atención, los estándares de oro, el entrenamiento, la asignación y las cuotas funcionan igual en todas las plataformas. El traslado se hace en cinco pasos:

Elige una plataforma. Prolific y CloudResearch Connect reclutan poblaciones de investigación generales, SONA atiende al grupo de participantes propio de una universidad, y Clickworker y Microworkers son comunidades abiertas de microtareas que necesitan un control de calidad más estricto.
Cambia el inicio de sesión. Mantén login.type: url_direct y cambia login.url_argument de workerId al parámetro de ID de la nueva plataforma (PROLIFIC_PID, sona_code, participantId, worker_id o mw_id).
Sustituye los bloques de plataforma. Elimina el bloque mturk, porque Potato sigue iniciando su cliente de la API de MTurk mientras ese bloque esté presente, y añade el bloque crowdsourcing de la nueva plataforma que aparece en esta página.
Sustituye el HIT. Crea el estudio o proyecto en la nueva plataforma, apunta su URL externa a tu servidor con el marcador de ID de la plataforma en el enlace, y configura el código de finalización o la redirección que te proporcione.
Conserva los controles de calidad. Deja attention_checks, gold_standards y la fase de entrenamiento como estaban, para que los resultados sigan siendo comparables con los datos de MTurk.

Control de calidad

Verificaciones de atención

Ítems con respuestas conocidas, mezclados en la cola:

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 detecta el modo de fallo al que más expuesto está el crowdsourcing, que es avanzar haciendo clic más rápido de lo que nadie podría leer el ítem.

Estándares de oro

Los ítems etiquetados por expertos miden la precisión y no la atención, y por defecto no dan ninguna señal, para que los trabajadores no reciban retroalimentación que les enseñe las respuestas:

yaml

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

Consulta Control de calidad para ver los formatos de los ítems y cómo se informa de ambos.

Páginas de finalización personalizadas

La página de finalización integrada muestra un código y un botón de retorno. Si necesitas algo más, termina el estudio con una página de surveyflow:

yaml

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

La página final es un ítem pure_display que lleva el enlace o el texto que necesites:

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

Ejemplo completo: estudio en 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

Seguimiento del estudio

El panel de administración en /admin informa de las tasas de finalización, el tiempo por instancia y los resultados de las verificaciones de atención mientras el estudio está en marcha. Para acceder se necesita la clave compartida admin_api_key o un rol que incluya view_admin_dashboard:

yaml

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

Exporta las anotaciones recogidas con la CLI de exportación:

bash

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

Buenas prácticas

Haz primero un piloto: prueba con unos pocos trabajadores antes de lanzar a gran escala
Paga de forma justa: cronometra la tarea tú mismo y fija el precio según la duración real
Escribe instrucciones claras: incluye ejemplos y los casos límite que esperas
Usa verificaciones de atención: detecta pronto a quien avanza haciendo clic sin leer, no durante el análisis
Añade estándares de oro: la atención y la precisión son mediciones distintas
Vigila el panel: los problemas son baratos de arreglar el primer día y caros el quinto
Decide de antemano los criterios de rechazo: los trabajadores deben conocer el estándar antes de empezar
Exporta con regularidad: no esperes a que cierre el estudio

Lecturas adicionales

Cómo realizar un estudio de crowdsourcing: reclutamiento, pago y control de calidad
Integración con MTurk: qué cambió con el cierre de MTurk
Inicio de sesión sin contraseña: autenticación basada en URL
Control de calidad: verificaciones de atención y estándares de oro
Gestión de usuarios: listas de acceso, roles y cuotas

Para detalles de implementación, consulta la documentación fuente, la referencia de Prolific y el panorama de plataformas.