Skip to content

تكامل التعهيد الجماعي

شغّل دراسات Potato على Prolific أو SONA أو CloudResearch Connect أو أي لوحة مشاركين تمرر معرّف المشارك، مع تسجيل دخول عبر URL ورموز إكمال وفحوصات انتباه.

يجمع Potato التعليقات التوضيحية من التعهيد الجماعي بقراءة معرّف المشارك من عنوان URL الذي ترسل إليه المنصة المشاركين، ثم يعرض رمز إكمال في النهاية. لكل من Prolific ومجمّعات المشاركين في SONA وCloudResearch Connect وClickworker وMicroworkers مزوّد خاص، ويغطي المزوّد generic أي لوحة مشاركين أخرى تعمل بالطريقة نفسها. أُغلق Amazon Mechanical Turk في 30 سبتمبر 2026، لذا يجب نقل أي دراسة كانت تعمل عليه إلى إحدى هذه المنصات، ويسرد قسم «نقل دراسة من MTurk» أدناه الخطوات.

التشغيل على منفذ مفتوح

يجب أن يتمكن العامل من الوصول إلى الخادم، لذا شغّله على منفذ مفتوح للإنترنت:

bash
potato start your-project -p 8080

يصل العمال بعد ذلك إلى https://your-server:8080/. ضع وكيلًا عكسيًا أمامه لتوفير TLS، كما هو موضح في إعداد الإنتاج.

مزوّدو التعهيد الجماعي

تحدد كتلة crowdsourcing المنصة. لكل من Prolific وSONA وConnect وClickworker وMicroworkers مزوّد مخصص، ويتعامل generic مع أي لوحة مشاركين تمرر معرّفًا في عنوان URL وتقبل رمز إكمال، مثل 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.

يقرأ كل مزوّد معرّف المشارك من معامل URL الذي يحدده login.url_argument، لذا أبقِ login.type: url_direct إلى جانب كتلة crowdsourcing واضبط url_argument على قيمة id_param الخاصة بالمزوّد. وتسجيل الدخول url_direct هو أيضًا ما يلغي طلب كلمة المرور. أما الإعداد الذي لا يحتوي على كتلة crowdsourcing فيحتفظ بالسلوك الأقدم، حيث يقرأ تسجيل الدخول وحده المعرّف، ويعتمد عليه الحد الأدنى من إعداد Prolific أدناه.

Prolific

الحد الأدنى من الإعداد

يكفي إعدادان لتشغيل دراسة على Prolific:

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

يسجَّل دخول العمال القادمين من Prolific باستخدام PROLIFIC_PID الخاص بهم دون طلب كلمة مرور. وعند الانتهاء، يرون رمز الإكمال وزرًا للعودة إلى Prolific.

مزوّد Prolific

يضيف المزوّد prolific رمزًا ثانيًا للمشاركين الذين لا يكملون المهمة. فالمشارك الذي تحظره فحوصات الانتباه، أو الذي يخفق في مرحلة التدريب، يحصل على 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 كلًا من SESSION_ID وSTUDY_ID إلى جانب معرّف المشارك.

إعادة التوجيه عند الإكمال

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

بدون إعادة التوجيه، تعرض الصفحة النهائية الرمز مع إمكانية نسخه بنقرة وزر للعودة، وهذا هو الخيار الافتراضي الأكثر أمانًا عندما تريد أن يحتفظ العمال بنسخة من الرمز.

التكامل مع واجهة Prolific البرمجية

في الدراسات الأكبر، يمكن لـ Potato التواصل مع واجهة Prolific البرمجية، مما يتيح له تحرير الأماكن التي يشغلها عمال أعادوا المهمة أو انتهت مهلتهم، وإيقاف الدراسة مؤقتًا عندما يكون الخادم مشغولًا. ضع بيانات الاعتماد في ملف مستقل:

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 معطلًا ما لم تفعّله. وعند تفعيله، يوقف Potato الدراسة مؤقتًا عندما يتجاوز عدد العمال النشطين max_concurrent_sessions، ويستأنفها عندما ينخفض عددهم إلى 20% من ذلك الرقم، ولكن فقط إذا كان المراقب نفسه هو الذي أوقف الدراسة. أما الدراسة التي أوقفتها يدويًا فلا يعيد Potato تشغيلها نيابةً عنك أبدًا.

استرداد العمل المتروك

عندما يعود إرسال بالحالة 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 هذا الرمز معرّفًا للمشارك:

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، فلا يحتاج المشارك إلى اتباع رابط للعودة إلى SONA. وإذا فشل هذا الاستدعاء، تعرض الصفحة النهائية بدلًا منه رابط منح الرصيد من جهة العميل في SONA. ويُسجَّل كل منح في حالة المشارك، لذا فإن إعادة تحميل الصفحة النهائية لا تمنح الرصيد مرتين أبدًا.

CloudResearch Connect

يرسل Connect المشاركين إلى دراسة خارجية عبر Project Link الخاص به، مع معرّف المشارك في participantId، واختياريًا assignmentId وprojectId. ويسجل Potato الثلاثة جميعًا. ويتم الإكمال برمز ثابت، أو بإعادة توجيه إلى عنوان URL الخاص بالإكمال المعروض في إعدادات مشروع 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 واجهة REST البرمجية الخاصة بـ Connect، لذا تتم الموافقات والمكافآت داخل Connect.

Clickworker

ترسل طلبات الاستبيانات الخارجية في Clickworker العمالَ إلى عنوان 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. هذا الإشعار الراجع (postback) تجريبي، لأن عقده لم يكن ممكنًا التحقق منه في توثيق عام، ويبقى معطلًا ما لم يضبط الإعداد experimental: true إلى جانب postback_url.

Microworkers

تطلب حملات Microworkers من كل عامل أن يلصق رمز تحقق يُسمّى VCODE ليثبت أنه أنهى العمل. يشتق Potato رمز VCODE لكل عامل من HMAC محسوب على معرّفي العامل والحملة، لذا يحصل العامل نفسه دائمًا على الرمز نفسه، ولا يستطيع أحد تخمين رمز دون السر، ويعيد التابع 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

اضبط عنوان URL للحملة على Microworkers على https://your-server.com/?mw_id={{MW_ID}}&campaign_id={{CAMP_ID}}&slot_id={{SLOT_ID}}. منصة Microworkers حشد مفتوح للمهام الصغيرة، لذا اقرنها بفحوصات الانتباه والمعايير الذهبية الموضحة أدناه.

Amazon Mechanical Turk (مغلق)

أُغلق Amazon Mechanical Turk نهائيًا في 30 سبتمبر 2026، ولم يعد يقبل مهام HIT أو يرسل عمالًا. لا يزال المزوّد mturk في Potato وتسجيل الدخول عبر workerId يُحمَّلان، لذا يبدأ تشغيل إعداد MTurk المؤرشف، لكن لا يستطيع أي عامل الوصول إليه. وتحتفظ صفحة تكامل MTurk بالتفاصيل لمن يقرأ إعداد دراسة قديمة.

نقل دراسة من MTurk

ينتقل معظم إعداد دراسة MTurk دون تغيير، لأن فحوصات الانتباه والمعايير الذهبية والتدريب والإسناد والحصص تعمل بالطريقة نفسها على كل منصة. ويتم النقل في خمس خطوات:

  1. اختر منصة. يجنّد Prolific وCloudResearch Connect مجموعات بحثية عامة، ويخدم SONA مجمّع المشاركين الخاص بالجامعة، أما Clickworker وMicroworkers فحشود مفتوحة للمهام الصغيرة تحتاج إلى مراقبة جودة أشد.
  2. غيّر تسجيل الدخول. أبقِ login.type: url_direct، وغيّر login.url_argument من workerId إلى معامل المعرّف الخاص بالمنصة الجديدة (PROLIFIC_PID أو sona_code أو participantId أو worker_id أو mw_id).
  3. استبدل كتل المنصة. احذف كتلة mturk، لأن Potato لا يزال يشغّل عميل واجهة MTurk البرمجية ما دامت هذه الكتلة موجودة، وأضف كتلة crowdsourcing الخاصة بالمنصة الجديدة من هذه الصفحة.
  4. استبدل مهمة HIT. أنشئ الدراسة أو المشروع على المنصة الجديدة، ووجّه عنوان URL الخارجي الخاص بها إلى خادمك مع العنصر النائب لمعرّف المنصة في الرابط، واضبط رمز الإكمال أو إعادة التوجيه التي تعطيك إياها.
  5. حافظ على ضوابط الجودة. اترك 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

صدّر التعليقات التوضيحية المجمّعة باستخدام أداة التصدير من سطر الأوامر:

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

أفضل الممارسات

  1. ابدأ بتجربة أولية: شغّل المهمة مع عدد قليل من العمال قبل الإطلاق على نطاق واسع
  2. ادفع أجرًا عادلًا: قِس وقت المهمة بنفسك وحدد الأجر وفق مدتها الفعلية
  3. اكتب تعليمات واضحة: أدرج أمثلة والحالات الحدية التي تتوقعها
  4. استخدم فحوصات الانتباه: اكتشف النقر دون قراءة مبكرًا بدلًا من اكتشافه عند التحليل
  5. أضف معايير ذهبية: الانتباه والدقة قياسان مختلفان
  6. تابع لوحة التحكم: إصلاح المشكلات رخيص في اليوم الأول ومكلف في اليوم الخامس
  7. حدد معايير الرفض مسبقًا: يجب أن يعرف العمال المعيار قبل أن يبدأوا
  8. صدّر البيانات بانتظام: لا تنتظر حتى تُغلق الدراسة

قراءة إضافية

لمزيد من تفاصيل التنفيذ، راجع التوثيق المصدري ومرجع Prolific ومسح المنصات.