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:

Start in the external platform (Prolific, MTurk, etc.)
Complete your PEBL study
Return automatically with a completion code
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:

Variable	Description	Example
`{COMPLETION_CODE}`	Generated completion code	`PEBL-ABC123-X9Y2`
`{PARTICIPANT}`	Participant ID	`SUBJ001` or `5`
`{SESSION}`	Session UUID	`a1b2c3d4-...`
`{CHAIN}`	Chain ID	`CHAIN_xyz`
`{TOKEN}`	Study token	`STUDY_ABC`
`{TIMESTAMP}`	Unix timestamp	`1730400000`
`{RANDOM}`	Random 16-char hex	`A3F9D2E8...`

Important: Platform variables (like {{%PROLIFIC_PID%}}) 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:

Go to Test Chains tab
Select your chain
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_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_xxx&token=STUDY_xxx&participant={{%PROLIFIC_PID%}}

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

4. Create Prolific Study

Go to Prolific and click New Study
In "Study link" field, paste your PEBL chain URL
Set completion code type to "I'll use a code"
Set completion code source to "URL"
Complete other study settings
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_CODE}

2. Create External HIT

In MTurk Requester interface, select New Batch → Other → Create Project
Choose Survey Link layout
In the survey link field, enter your PEBL chain URL:

   https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN_xxx&token=STUDY_xxx&participant={{workerId}}

Configure:

Reward per assignment: Your payment amount

Number of assignments: Number of participants
Time allotted: Realistic estimate + buffer
Auto-approval delay: 1-3 days typical

Publish HIT

Important Notes

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

Testing

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

---

SONA Systems

Use Case: University participant pools with automated credit granting.

Setup Steps

1. Get SONA Credit URLs

From your SONA system:

Go to study configuration
Find the credit granting URL format
Note your experiment ID and credit token

Typical format:

https://yourschool.sona-systems.com/webstudy_credit.aspx?experiment_id=XXX&credit_token=YYY&survey_code={PARTICIPANT}

2. Configure Completion Settings

Completion Code Format: Leave empty (auto-redirect)

Redirect URL: Your SONA credit URL (from above)

Important: Replace XXX with your experiment ID and YYY with your credit token

3. Get SONA Participant IDs

SONA provides participant IDs via URL parameter.

Your SONA study URL should be:

https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN_xxx&token=STUDY_xxx&participant=%%SURVEY_CODE%%

Note: SONA uses %%SURVEY_CODE%% which it replaces with the participant's ID.

Behavior

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

Best Practices

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

Qualtrics Integration

Use Case: Combine PEBL tests with surveys, demographics, or debriefing.

Setup Method 1: PEBL → Qualtrics

Send participants to Qualtrics after completing PEBL study.

Configuration

Completion Code Format:

Q-{PARTICIPANT}-{RANDOM}

Redirect URL:

https://yoursurvey.qualtrics.com/jfe/form/SV_XXXXXXX?pebl_code={COMPLETION_CODE}&pebl_participant={PARTICIPANT}

Replace SV_XXXXXXX with your Qualtrics survey ID.

In Qualtrics

Edit your survey
Go to Survey Flow
Add Embedded Data fields:

pebl_code

pebl_participant

4. Move embedded data block to top of survey flow

Use these fields in your survey or data analysis

Example: Show completion code in end-of-survey message:

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

Setup Method 2: Qualtrics → PEBL

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

In Qualtrics

Add an end-of-survey element
Set redirect to your PEBL chain URL:

   https://peblhub.online/runtime/chain-launcher.html?chain=CHAIN_xxx&token=STUDY_xxx&participant=${e://Field/ResponseID}

Configure PEBL completion to redirect back to a Qualtrics confirmation page (optional)

Best Practices

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

SurveyMonkey Integration

Use Case: Combine PEBL tests with survey questions.

Setup Steps

1. Configure Completion Settings

Completion Code Format:

SM-{PARTICIPANT}

Redirect URL:

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

Replace XXXXXXX with your SurveyMonkey survey ID.

2. In SurveyMonkey

Edit your survey
Add Custom Variables:

Name: code, Value: (will be filled from URL)

Name: participant, Value: (will be filled from URL)

(Optional) Display the code in survey:

Add a text block

Reference: [variable("code")]

Best Practices

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

Custom/Internal Platforms

Use Case: Your own website, LMS, or participant management system.

Basic Setup

Completion Code Format (your choice):

CUSTOM-{PARTICIPANT}-{TIMESTAMP}

Redirect URL (your endpoint):

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

With Server Callback

For more reliable tracking, use a callback URL:

Callback URL:

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

Callback receives POST data:

{
  "session_id": "uuid-here",
  "participant_id": "PARTICIPANT_123",
  "chain_id": "CHAIN_xyz",
  "token_id": "STUDY_ABC",
  "completion_code": "CUSTOM-PARTICIPANT_123-1730000000",
  "status": "completed",
  "timestamp": "2025-10-31T12:00:00Z"
}

Implementation Example (PHP)

// Your endpoint: /api/grant-credit
$data = json_decode(file_get_contents('php://input'), true);

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

    // Log completion
    logCompletion($data);

    // Respond
    http_response_code(200);
    echo json_encode(['success' => true]);
}

Benefits of Callback

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

Advanced Scenarios

Auto-Redirect Without Code

When: Platform handles credit via callback, no manual code needed.

Configuration:

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

Result: "You will be redirected in 5 seconds..." with no code displayed.

Code Display Only (No Redirect)

When: Participants manually enter code elsewhere (email, Google Form, etc.).

Configuration:

Completion Code Format: CODE-{PARTICIPANT}
Redirect URL: Leave empty

Result: Shows completion code with "You may now close this window" message.

Server Notification + Redirect

When: Want both server verification AND participant redirect with code.

Configuration:

Completion Code Format: VERIFY-{PARTICIPANT}-{RANDOM}
Redirect URL: https://platform.com/done?code={COMPLETION_CODE}
Callback URL: https://platform.com/api/notify

Result:

Server receives POST notification immediately
Participant sees completion code
Manual redirect button available

---

Platform Comparison

Platform	Best For	Credit Method	Code Needed?
Prolific	Professional recruitment	Automatic via URL	Optional
MTurk	Large-scale recruitment	External submit	Required
SONA	University pools	Auto credit grant	No
Qualtrics	Surveys + tests	Manual or piped text	Optional
SurveyMonkey	Simple surveys + tests	Manual variables	Optional
Custom	Full control	Your implementation	Your choice

Troubleshooting

Redirect Not Working

Causes:

Incorrect URL format
Missing required variables for platform
Browser blocking redirect

Solutions:

Test the redirect URL directly in browser
Check browser console (F12) for errors
Verify all template variables are present
Try different browser (some block redirects)

Completion Code Not Appearing in Platform

Causes:

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

Solutions:

Verify {COMPLETION_CODE} in redirect URL
Check platform's custom variable/embedded data settings
Ensure variable names match (case-sensitive)

Participants Not Receiving Credit

Causes:

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

Solutions:

Test complete flow yourself as participant
Check platform's current API documentation
Verify credit granting settings in platform
Use callback URL for more reliable tracking

Platform Variables Not Replacing

Causes:

Variable formatted incorrectly for platform
URL encoding breaking platform variable format

Solutions:

Prolific: Use {{%PROLIFIC_PID%}} (double braces, percent signs)
MTurk: Use {{workerId}} and {{assignmentId}} (double braces)
SONA: Use %%SURVEY_CODE%% (double percent signs)
Qualtrics: Use ${e://Field/ResponseID} (dollar sign, braces)

Security Considerations

Best Practices

Never include sensitive credentials in URLs

Use environment variables or config files

Keep API keys server-side only

Use HTTPS for all callback URLs

Encrypt data in transit

Prevent man-in-the-middle attacks

Validate completion codes on your server

Don't rely solely on client-side redirect

Verify code format and uniqueness
Check timestamp isn't too old (prevent replay)

Use callback URLs for credit granting

More secure than client-side redirect

Participant can't manipulate server-to-server communication
Verify before granting credit

Example: Validation Logic

function validateCompletionCode($code, $participant, $timestamp) {
    // Check format
    if (!preg_match('/^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

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

Platform-Specific Resources

Prolific: https://researcher-help.prolific.com
MTurk: https://requester.mturk.com/help
SONA: Contact your institution's SONA administrator
Qualtrics: https://www.qualtrics.com/support/
SurveyMonkey: https://help.surveymonkey.com

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

Platform Integration Guide

What You'll Learn

Overview

Template Variables

Prolific Integration

Setup Steps

1. Create Your Test Chain

2. Configure Completion Settings

3. Get Your Study URL

4. Create Prolific Study

Behavior

Best Practices

Amazon Mechanical Turk (MTurk)

Setup Steps

1. Configure Completion Settings

2. Create External HIT

Important Notes

Testing

SONA Systems

Setup Steps

1. Get SONA Credit URLs

2. Configure Completion Settings

3. Get SONA Participant IDs

Behavior

Best Practices

Qualtrics Integration

Setup Method 1: PEBL → Qualtrics

Configuration

In Qualtrics

Setup Method 2: Qualtrics → PEBL

In Qualtrics

Best Practices

SurveyMonkey Integration

Setup Steps

1. Configure Completion Settings

2. In SurveyMonkey

Best Practices

Custom/Internal Platforms

Basic Setup

With Server Callback

Implementation Example (PHP)

Benefits of Callback

Advanced Scenarios

Auto-Redirect Without Code

Code Display Only (No Redirect)

Server Notification + Redirect

Platform Comparison

Troubleshooting

Redirect Not Working

Completion Code Not Appearing in Platform

Participants Not Receiving Credit

Platform Variables Not Replacing

Security Considerations

Best Practices

Example: Validation Logic

Testing Your Integration

Pre-Launch Checklist

Common Test Scenarios

Platform-Specific Resources

Related Topics

Related Topics