← Help Index
Category: Platform Integration Level: Intermediate Reading time: 20 minutes Updated: 2025-10-31

Platform Integration Guide

Quick Summary: Connect your PEBL studies with external recruitment platforms like Prolific, MTurk, SONA, Qualtrics, and SurveyMonkey for seamless participant management and credit granting.

What You'll Learn

  • How to integrate with popular recruitment platforms
  • Setting up completion codes and redirects
  • Using template variables for participant tracking
  • Configuring auto-redirect vs. manual redirect
  • Troubleshooting integration issues

Overview

The PEBL Online Platform integrates with external participant recruitment and survey platforms, allowing participants to:

  1. Start in the external platform (Prolific, MTurk, etc.)
  2. Complete your PEBL study
  3. Return automatically with a completion code
  4. Receive credit in the external platform
This guide provides setup instructions for each major platform.

Template Variables

Use these variables in your completion codes and redirect URLs:

VariableDescriptionExample--------------------------------{COMPLETIONCODE}Generated completion codePEBL-ABC123-X9Y2{PARTICIPANT}Participant IDSUBJ001 or 5{SESSION}Session UUIDa1b2c3d4-...{CHAIN}Chain IDCHAINxyz{TOKEN}Study tokenSTUDYABC{TIMESTAMP}Unix timestamp1730400000{RANDOM}Random 16-char hexA3F9D2E8...Important: Platform variables (like {{%PROLIFICPID%}}) are NOT encoded when used in URLs, allowing the platform to replace them correctly.

Prolific Integration

Use Case: Professional participant recruitment with built-in quality controls.

Setup Steps

1. Create Your Test Chain

In PEBL Online Platform:

  1. Go to Test Chains tab
  2. Select your chain
  3. Click Edit Completion Page

2. Configure Completion Settings

Completion Code Format (optional):

PEBL-{PARTICIPANT}-{RANDOM}

Redirect URL:

https://app.prolific.com/submissions/complete?cc={COMPLETION<em>CODE}

Callback URL: Leave empty (not needed)

3. Get Your Study URL

Your chain URL will look like:

https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN</em>xxx&token=STUDY<em>xxx&participant={{%PROLIFIC</em>PID%}}

Note the {{%PROLIFICPID%}} variable - Prolific will replace this with each participant's actual ID.

4. Create Prolific Study

  1. Go to Prolific and click New Study
  2. In "Study link" field, paste your PEBL chain URL
  3. Set completion code type to "I'll use a code"
  4. Set completion code source to "URL"
  5. Complete other study settings
  6. Publish your study

Behavior

If completion code format is set:

  • Participant sees completion code on screen
  • Click "Return to Prolific" button manually
  • Gives time to copy/record code if needed

If completion code format is empty:

  • Automatic redirect after 5 seconds
  • No code displayed
  • Faster participant experience

Best Practices

  • Test first: Use Prolific's preview mode to test the full flow
  • Use completion codes: Helps verify participants completed your study
  • Set realistic time estimate: Include time for test + reading instructions
  • Check browser requirements: Ensure mobile/desktop settings match your tests

Amazon Mechanical Turk (MTurk)

Use Case: Large-scale participant recruitment with flexible payment options.

Setup Steps

1. Configure Completion Settings

Completion Code Format:

MTURK-{TIMESTAMP}

Redirect URL:

https://www.mturk.com/mturk/externalSubmit?assignmentId={{assignmentId}}&code={COMPLETION</em>CODE}

2. Create External HIT

  1. In MTurk Requester interface, select New Batch → Other → Create Project
  2. Choose Survey Link layout
  3. In the survey link field, enter your PEBL chain URL:
   https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN<em>xxx&token=STUDY</em>xxx&participant={{workerId}}

``



  1. Configure:
  • <strong>Reward per assignment</strong>: Your payment amount
    • <strong>Number of assignments</strong>: Number of participants
    • <strong>Time allotted</strong>: Realistic estimate + buffer
    • <strong>Auto-approval delay</strong>: 1-3 days typical


  1. Publish HIT
<h3>Important Notes</h3>


  • MTurk's external submit endpoint URL may change - always check current MTurk documentation
  • Use {{workerId}} variable for participant tracking
  • {{assignmentId}} is required for submission to count
  • Preview mode: Test with MTurk sandbox before going live


<h3>Testing</h3>



  1. Use MTurk Sandbox (requestersandbox.mturk.com)
  2. Create test HIT with $0.01 reward
  3. Accept as worker (different account)
  4. Complete study and verify redirect works
---


<h2>SONA Systems</h2>



<strong>Use Case</strong>: University participant pools with automated credit granting.



<h3>Setup Steps</h3>



<h4>1. Get SONA Credit URLs</h4>



From your SONA system:


  1. Go to study configuration
  2. Find the credit granting URL format
  3. Note your experiment ID and credit token
Typical format:

https://yourschool.sona-systems.com/webstudycredit.aspx?experimentid=XXX&credittoken=YYY&surveycode={PARTICIPANT}



<h4>2. Configure Completion Settings</h4>



<strong>Completion Code Format</strong>: Leave <strong>empty</strong> (auto-redirect)



<strong>Redirect URL</strong>: Your SONA credit URL (from above)



<strong>Important</strong>: Replace XXX with your experiment ID and YYY with your credit token



<h4>3. Get SONA Participant IDs</h4>



SONA provides participant IDs via URL parameter.


Your SONA study URL should be:

https://peblhub.online/runtime/chain-launcher.html?chain=CHAINxxx&token=STUDYxxx&participant=%%SURVEYCODE%%



<strong>Note</strong>: SONA uses %%SURVEY</em>CODE%% which it replaces with the participant's ID.



<h3>Behavior</h3>



  • Participant completes PEBL study
  • Automatic redirect to SONA (5 seconds)
  • SONA grants credit immediately
  • Participant sees confirmation in SONA


<h3>Best Practices</h3>



  • <strong>Test with test participant</strong>: Use SONA's test participant feature
  • <strong>Set appropriate credit</strong>: Match credits to time + complexity
  • <strong>Enable re-do option</strong>: Allow participants to restart if technical issues
  • <strong>Monitor credit grants</strong>: Check SONA logs to verify automatic granting works





<h2>Qualtrics Integration</h2>



<strong>Use Case</strong>: Combine PEBL tests with surveys, demographics, or debriefing.



<h3>Setup Method 1: PEBL → Qualtrics</h3>



Send participants to Qualtrics after completing PEBL study.



<h4>Configuration</h4>


<strong>Completion Code Format</strong>:

Q-{PARTICIPANT}-{RANDOM}


<strong>Redirect URL</strong>:

https://yoursurvey.qualtrics.com/jfe/form/SVXXXXXXX?peblcode={COMPLETIONCODE}&peblparticipant={PARTICIPANT}



Replace SV<em>XXXXXXX with your Qualtrics survey ID.



<h4>In Qualtrics</h4>



  1. Edit your survey
  2. Go to <strong>Survey Flow</strong>
  3. Add <strong>Embedded Data</strong> fields:
  • pebl</em>code
    • pebl<em>participant
4. Move embedded data block to top of survey flow

  1. Use these fields in your survey or data analysis
<strong>Example</strong>: Show completion code in end-of-survey message:

Thank you! Your completion code is ${e://Field/peblcode}



<h3>Setup Method 2: Qualtrics → PEBL</h3>



Start in Qualtrics (demographics first), then send to PEBL.



<h4>In Qualtrics</h4>



  1. Add an end-of-survey element
  2. Set redirect to your PEBL chain URL:
   `

https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN<em>xxx&token=STUDY</em>xxx&participant=${e://Field/ResponseID} `



  1. Configure PEBL completion to redirect back to a Qualtrics confirmation page (optional)
<h3>Best Practices</h3>


  • <strong>Use Response ID</strong>: Qualtrics's ${e://Field/ResponseID} is unique per participant
  • <strong>Test the flow</strong>: Complete both PEBL and Qualtrics as a test participant
  • <strong>Piped text</strong>: Use Qualtrics piped text to display codes/IDs
  • <strong>Embedded data</strong>: Capture PEBL completion status in Qualtrics for data validation





<h2>SurveyMonkey Integration</h2>



<strong>Use Case</strong>: Combine PEBL tests with survey questions.



<h3>Setup Steps</h3>



<h4>1. Configure Completion Settings</h4>


<strong>Completion Code Format</strong>:

SM-{PARTICIPANT}


<strong>Redirect URL</strong>:

https://www.surveymonkey.com/r/XXXXXXX?code={COMPLETIONCODE}&participant={PARTICIPANT}



Replace XXXXXXX with your SurveyMonkey survey ID.



<h4>2. In SurveyMonkey</h4>



  1. Edit your survey
  2. Add <strong>Custom Variables</strong>:
  • Name: code, Value: (will be filled from URL)
    • Name: participant, Value: (will be filled from URL)


  1. (Optional) Display the code in survey:
  • Add a text block
    • Reference: [variable("code")]


<h3>Best Practices</h3>



  • <strong>Test the integration</strong>: Use SurveyMonkey's preview mode
  • <strong>Collect contact info carefully</strong>: Follow your IRB/ethics protocols
  • <strong>Use custom variables</strong>: Capture PEBL completion info for data linking





<h2>Custom/Internal Platforms</h2>



<strong>Use Case</strong>: Your own website, LMS, or participant management system.



<h3>Basic Setup</h3>


<strong>Completion Code Format</strong> (your choice):

CUSTOM-{PARTICIPANT}-{TIMESTAMP}


<strong>Redirect URL</strong> (your endpoint):

https://your-platform.com/study-complete?session={SESSION}&code={COMPLETIONCODE}&participant={PARTICIPANT}



<h3>With Server Callback</h3>



For more reliable tracking, use a callback URL:


<strong>Callback URL</strong>:

https://your-platform.com/api/grant-credit



<strong>Callback receives POST data</strong>:
json { "sessionid": "uuid-here", "participantid": "PARTICIPANT123", "chainid": "CHAINxyz", "tokenid": "STUDYABC", "completioncode": "CUSTOM-PARTICIPANT123-1730000000", "status": "completed", "timestamp": "2025-10-31T12:00:00Z" }



<h3>Implementation Example (PHP)</h3>
php // Your endpoint: /api/grant-credit $data = jsondecode(filegetcontents('php://input'), true);

if ($data['status'] === 'completed') { // Grant credit to participant grantCredit( $data['participantid'], $data['completioncode'] );

// Log completion logCompletion($data);

// Respond httpresponsecode(200); echo jsonencode(['success' => true]); }



<h3>Benefits of Callback</h3>



  • <strong>More reliable</strong>: Server-to-server notification doesn't depend on participant's browser
  • <strong>Executes first</strong>: Callback sent before redirect, so you can verify completion before participant arrives
  • <strong>Security</strong>: Can validate completion on your server before granting credit





<h2>Advanced Scenarios</h2>



<h3>Auto-Redirect Without Code</h3>



<strong>When</strong>: Platform handles credit via callback, no manual code needed.



<strong>Configuration</strong>:


  • <strong>Completion Code Format</strong>: Leave <strong>completely empty</strong>
  • <strong>Redirect URL</strong>: https://platform.com/done?session={SESSION}


<strong>Result</strong>: "You will be redirected in 5 seconds..." with no code displayed.



<h3>Code Display Only (No Redirect)</h3>



<strong>When</strong>: Participants manually enter code elsewhere (email, Google Form, etc.).



<strong>Configuration</strong>:


  • <strong>Completion Code Format</strong>: CODE-{PARTICIPANT}
  • <strong>Redirect URL</strong>: Leave <strong>empty</strong>


<strong>Result</strong>: Shows completion code with "You may now close this window" message.



<h3>Server Notification + Redirect</h3>



<strong>When</strong>: Want both server verification AND participant redirect with code.



<strong>Configuration</strong>:


  • <strong>Completion Code Format</strong>: VERIFY-{PARTICIPANT}-{RANDOM}
  • <strong>Redirect URL</strong>: https://platform.com/done?code={COMPLETION</em>CODE}
  • <strong>Callback URL</strong>: https://platform.com/api/notify


<strong>Result</strong>:


  1. Server receives POST notification immediately
  2. Participant sees completion code
  3. Manual redirect button available
---

<h2>Platform Comparison</h2>
PlatformBest ForCredit MethodCode Needed?
<strong>Prolific</strong>Professional recruitmentAutomatic via URLOptional
<strong>MTurk</strong>Large-scale recruitmentExternal submitRequired
<strong>SONA</strong>University poolsAuto credit grantNo
<strong>Qualtrics</strong>Surveys + testsManual or piped textOptional
<strong>SurveyMonkey</strong>Simple surveys + testsManual variablesOptional
<strong>Custom</strong>Full controlYour implementationYour choice

<h2>Troubleshooting</h2>

<h3>Redirect Not Working</h3>

<strong>Causes</strong>:

  • Incorrect URL format
  • Missing required variables for platform
  • Browser blocking redirect

<strong>Solutions</strong>:

  1. Test the redirect URL directly in browser
  2. Check browser console (F12) for errors
  3. Verify all template variables are present
  4. Try different browser (some block redirects)
<h3>Completion Code Not Appearing in Platform</h3>

<strong>Causes</strong>:

  • Code not included in redirect URL
  • Platform not configured to capture URL parameters
  • Variable name mismatch

<strong>Solutions</strong>:

  1. Verify {COMPLETION<em>CODE} in redirect URL
  2. Check platform's custom variable/embedded data settings
  3. Ensure variable names match (case-sensitive)
<h3>Participants Not Receiving Credit</h3>

<strong>Causes</strong>:

  • Redirect URL incorrect
  • Completion code not valid format for platform
  • Platform API changed

<strong>Solutions</strong>:

  1. Test complete flow yourself as participant
  2. Check platform's current API documentation
  3. Verify credit granting settings in platform
  4. Use callback URL for more reliable tracking
<h3>Platform Variables Not Replacing</h3>

<strong>Causes</strong>:

  • Variable formatted incorrectly for platform
  • URL encoding breaking platform variable format

<strong>Solutions</strong>:

  • Prolific: Use {{%PROLIFIC</em>PID%}} (double braces, percent signs)
  • MTurk: Use {{workerId}} and {{assignmentId}} (double braces)
  • SONA: Use %%SURVEY<em>CODE%% (double percent signs)
  • Qualtrics: Use ${e://Field/ResponseID} (dollar sign, braces)

<h2>Security Considerations</h2>

<h3>Best Practices</h3>

  1. <strong>Never include sensitive credentials in URLs</strong>
  • Use environment variables or config files
    • Keep API keys server-side only
  1. <strong>Use HTTPS for all callback URLs</strong>
  • Encrypt data in transit
    • Prevent man-in-the-middle attacks
  1. <strong>Validate completion codes on your server</strong>
  • Don't rely solely on client-side redirect
    • Verify code format and uniqueness
    • Check timestamp isn't too old (prevent replay)
  1. <strong>Use callback URLs for credit granting</strong>
  • More secure than client-side redirect
    • Participant can't manipulate server-to-server communication
    • Verify before granting credit

<h3>Example: Validation Logic</h3> php function validateCompletionCode($code, $participant, $timestamp) { // Check format if (!pregmatch('/^STUDY-[A-Z0-9]+-[A-F0-9]+$/', $code)) { return false; }

// Check timestamp isn't too old (within 24 hours) $maxAge = 86400; // 24 hours in seconds if (time() - $timestamp > $maxAge) { return false; }

// Check code hasn't been used before if (codeAlreadyUsed($code)) { return false; }

return true; } ``

Testing Your Integration

Pre-Launch Checklist

  • [ ] Test complete flow as participant (start to finish)
  • [ ] Verify completion code displays correctly
  • [ ] Check redirect works in multiple browsers
  • [ ] Confirm credit/payment granted in external platform
  • [ ] Test with platform's sandbox/test mode if available
  • [ ] Verify callback receives data correctly (if used)
  • [ ] Check data matches between PEBL and external platform
  • [ ] Test failure scenarios (participant closes browser mid-study)
  • [ ] Document the working configuration for future studies

Common Test Scenarios

  1. Happy path: Complete study normally
  2. Early exit: Close browser mid-study, return later
  3. Multiple attempts: Try to complete twice with same code
  4. Different browsers: Test on Chrome, Firefox, Safari
  5. Mobile: Test on mobile devices if participants will use them

Platform-Specific Resources

Warning: Platform APIs and requirements change over time. Always verify current requirements in the platform's official documentation before launching your study.

Related Topics

Need more help? Contact your platform's support team or consult their official documentation for the most current integration requirements.

Related Topics