クラウドソーシング統合

Prolific、SONA、CloudResearch Connect、または参加者IDを渡す任意のパネルでPotatoのスタディを実行します。URLログイン、完了コード、注意力チェックに対応しています。

Potatoは、プラットフォームが参加者を送るURLから参加者IDを読み取り、最後に完了コードを表示することで、クラウドソーシングのアノテーションを収集します。Prolific、SONAの被験者プール、CloudResearch Connect、Clickworker、Microworkersにはそれぞれプロバイダーがあり、同じ仕組みで動く他のパネルにはgenericプロバイダーで対応できます。Amazon Mechanical Turkは2026年9月30日に終了したため、そこで実施していたスタディはこれらのプラットフォームのいずれかに移す必要があります。手順は後述の「MTurkからスタディを移行する」の節にまとめています。

公開ポートでの実行

クラウドワーカーがサーバーにアクセスできる必要があるため、インターネットに公開されたポートで実行します：

bash

potato start your-project -p 8080

ワーカーはhttps://your-server:8080/にアクセスします。TLSのために前段にリバースプロキシを置いてください。手順は本番環境のセットアップで説明しています。

クラウドプロバイダー

crowdsourcingブロックでプラットフォームを指定します。Prolific、SONA、Connect、Clickworker、Microworkersには専用のプロバイダーがあり、genericはURLでIDを渡し完了コードを受け付けるパネル全般を扱います。Besample、Positly、User Interviews、Testable Minds、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では、プレースホルダー{code}、{worker_id}、{session_id}、{study_id}、およびcapture_paramsに列挙した任意の名前を使えます。

どのプロバイダーもlogin.url_argumentで指定したURLパラメータから参加者IDを読み取ります。そのため、crowdsourcingブロックと並べてlogin.type: url_directを残し、url_argumentをプロバイダーのid_paramに合わせてください。パスワード入力を省くのもurl_directログインの役割です。crowdsourcingブロックのない設定では従来の動作が維持され、ログインだけでIDを読み取ります。後述のProlificの最小構成はこの方式を使っています。

Prolific

最小構成

Prolificのスタディは2つの設定で実行できます：

yaml

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

Prolificから来たワーカーは、パスワードを求められることなくPROLIFIC_PIDでログインします。作業を終えると、完了コードとProlificに戻るボタンが表示されます。

Prolificプロバイダー

prolificプロバイダーは、タスクを完了しなかった参加者向けに2つ目のコードを追加します。注意力チェックでブロックされた参加者や、トレーニングフェーズに合格しなかった参加者には、完了コードの代わりにfailed_codeが渡されます：

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

スタディURL

Prolificのスタディ設定で、URLを次のように設定します：

text

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

Prolificが実際の値に置き換えます。Potatoは参加者IDとあわせてSESSION_IDとSTUDY_IDを記録します。

完了時のリダイレクト

yaml

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

リダイレクトを使わない場合、完了ページにはクリックでコピーできるコードと戻るボタンが表示されます。ワーカーにコードを控えておいてほしい場合は、こちらのほうが安全なデフォルトです。

Prolific API連携

大規模なスタディでは、PotatoがProlific APIと通信できます。これにより、返却またはタイムアウトしたワーカーが確保していた枠を解放し、サーバーが混雑しているときにスタディを一時停止できます。認証情報は専用のファイルに記述します：

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

次に、メインの設定ファイルからそのファイルを参照します：

yaml

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

workload_checkerは有効にしない限りオフです。有効にすると、アクティブなワーカー数がmax_concurrent_sessionsを超えたときにPotatoがスタディを一時停止し、その数の20%まで下がったときに再開します。ただし再開するのは、モニター自身がスタディを一時停止した場合に限ります。手動で一時停止したスタディが自動で再開されることはありません。

放棄された作業の回収

提出がRETURNED、TIMED-OUT、REJECTEDのいずれかで戻ってくると、Potatoはそのワーカーに割り当てられたまま未アノテーションのアイテムを解放し、他の人が担当できるようにします。すでに完了したアノテーションは保持されます。instance_reclaimでこの動作をステータスごとに変更できます：

yaml

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

SONA被験者プール

SONA Systemsは、多くの大学が授業の単位付与に使う参加者プールを運営しています。SONAは参加者ごとに固有のコードをスタディURLに埋め込み、Potatoはそのコードを参加者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

SONAでは、スタディURLをhttps://your-server.com/?sona_code=%SURVEY_CODE%に設定します。参加者が作業を終えると、PotatoがSONAのサーバー側クレジット付与APIを呼び出して自らクレジットを付与するので、参加者がリンクをたどってSONAに戻る必要はありません。この呼び出しが失敗した場合は、代わりにSONAのクライアント側クレジット付与リンクが完了ページに表示されます。付与はそれぞれ参加者の状態に記録されるため、完了ページを再読み込みしてもクレジットが二重に付与されることはありません。

CloudResearch Connect

ConnectはProject Linkを通じて参加者を外部のスタディに送ります。参加者のIDはparticipantIdに入り、任意でassignmentIdとprojectIdも付きます。Potatoはこの3つをすべて記録します。完了は固定のコードか、Connectのプロジェクト設定に表示される完了URLへのリダイレクトで行います：

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はConnectのREST APIを呼び出さないため、承認とボーナスの支払いはConnect上で行います。

Clickworker

Clickworkerの外部アンケート型の注文では、ワーカーがIDを付けてあなたのURLに送られ、完了は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"

このプロバイダーは、ClickworkerのマーケットプレイスAPIを通じて支払いを発生させる完了通知を送ることもできます。このポストバックは実験的な機能です。その仕様を公開ドキュメントで確認できなかったためで、設定でpostback_urlと並べてexperimental: trueを指定しない限りオフのままです。

Microworkers

Microworkersのキャンペーンでは、作業を終えた証明として、VCODEと呼ばれる確認コードを各ワーカーに貼り付けて返してもらいます。PotatoはワーカーIDとキャンペーンIDから計算したHMACで各ワーカーのVCODEを導き出します。そのため、同じワーカーには常に同じコードが渡され、シークレットを知らない人がコードを推測することはできず、プロバイダーのverify_vcodeメソッドはコードを再計算して提出内容を確認できます：

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

MicroworkersのキャンペーンURLはhttps://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}に設定します。Microworkersは誰でも参加できるマイクロタスクのクラウドなので、後述の注意力チェックとゴールドスタンダードを組み合わせてください。

Amazon Mechanical Turk（終了）

Amazon Mechanical Turkは2026年9月30日に完全に終了し、HITの受け付けもワーカーの送り出しも行っていません。PotatoのmturkプロバイダーとworkerIdログインは今も読み込まれるので、保存してあるMTurkの設定は起動しますが、そこにたどり着けるワーカーはいません。MTurk統合のページには、過去のスタディの設定を読む人のために詳細を残しています。

MTurkからスタディを移行する

MTurkスタディの設定の大部分はそのまま引き継げます。注意力チェック、ゴールドスタンダード、トレーニング、割り当て、上限設定はどのプラットフォームでも同じように動くからです。移行は5つの手順で行います：

プラットフォームを選ぶ。 ProlificとCloudResearch Connectは一般的な研究対象者を募集し、SONAは大学独自のプールに対応します。ClickworkerとMicroworkersは誰でも参加できるマイクロタスクのクラウドで、より強い品質管理が必要です。
ログインを変更する。 login.type: url_directはそのままにして、login.url_argumentをworkerIdから新しいプラットフォームのIDパラメータ（PROLIFIC_PID、sona_code、participantId、worker_id、mw_idのいずれか）に変更します。
プラットフォームのブロックを差し替える。 mturkブロックを削除します。このブロックがある限り、PotatoはMTurk APIクライアントを起動し続けるためです。そのうえで、新しいプラットフォームのcrowdsourcingブロックをこのページから追加します。
HITを置き換える。 新しいプラットフォームでスタディまたはプロジェクトを作成し、その外部URLを、プラットフォームのIDプレースホルダーを含むリンクでサーバーに向けます。そして、プラットフォームが発行する完了コードまたはリダイレクトを設定します。
品質管理を維持する。 attention_checks、gold_standards、トレーニングフェーズは元のまま残し、結果をMTurkのデータと比較できるようにします。

品質管理

注意力チェック

正解がわかっているアイテムをキューに混ぜます：

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は、クラウドソーシングが最もさらされやすい失敗、つまり誰にも読めない速さでクリックして進める行為を捉えます。

ゴールドスタンダード

専門家がラベル付けしたアイテムは注意力ではなく正確さを測ります。デフォルトではフィードバックを出さないので、ワーカーが正解を覚えてしまうことはありません：

yaml

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

アイテムの形式と両者のレポート方法については品質管理を参照してください。

カスタム完了ページ

組み込みの完了ページが扱うのはコードと戻るボタンです。それ以上が必要な場合は、代わりにsurveyflowのページでスタディを終えます：

yaml

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

終了ページは、必要なリンクやテキストを載せたpure_displayアイテムです：

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

完全な例：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

スタディの監視

/adminの管理者ダッシュボードでは、スタディの実行中に完了率、インスタンスあたりの時間、注意力チェックの結果を確認できます。アクセスには、共有のadmin_api_keyか、view_admin_dashboardを持つロールのいずれかが必要です：

yaml

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

収集したアノテーションはエクスポートCLIで書き出します：

bash

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

ベストプラクティス

まずパイロットを行う：大規模に始める前に少数のワーカーで試す
公正に支払う：自分でタスクの所要時間を測り、実際の時間に基づいて報酬を決める
明確な指示を書く：例と想定されるエッジケースを含める
注意力チェックを使う：読まずにクリックする行為を、分析段階ではなく早い段階で見つける
ゴールドスタンダードを加える：注意力と正確さは別の測定値である
ダッシュボードを確認する：問題は初日なら安く直せるが、5日目には高くつく
却下の基準を事前に決める：ワーカーは始める前に基準を知っているべきである
定期的にエクスポートする：スタディの終了まで待たない

クラウドソーシング統合

公開ポートでの実行

クラウドプロバイダー

Prolific

最小構成

Prolificプロバイダー

スタディURL

完了時のリダイレクト

Prolific API連携

放棄された作業の回収

SONA被験者プール

CloudResearch Connect

Clickworker

Microworkers

Amazon Mechanical Turk（終了）

MTurkからスタディを移行する

品質管理

注意力チェック

ゴールドスタンダード

カスタム完了ページ

完全な例：Prolificスタディ

スタディの監視

ベストプラクティス

関連情報