Figured it out: How to Embed Friendly Captcha in SoSci Survey
A Step-by-Step Integration Guide
STEP 1 Create a Friendly Captcha Account
Obtain your API credentials from the Friendly Captcha dashboard
Go to
https://app.friendlycaptcha.eu/dashboard and register for a free account.
The free plan allows up to 1,000 verification requests per month, which is sufficient for most academic studies. After registration, you need two credentials:
• Sitekey — a public identifier placed in your HTML widget. It tells Friendly Captcha which account to use.
• API Key — a secret key used server-side in your PHP code to verify tokens. Never share or expose this key publicly.
STEP 2 Add the Captcha Widget (HTML Text Element)
Embed the Friendly Captcha widget and token-copy script on your survey page
In SoSci Survey, create a new HTML-Code text element (I recommend adding it in a question block) and then drag it to the survey page where you want to check for bots.
The HTML-Code should read like so:
<!-- Load the Friendly Captcha widget -->
<script type="module"
src="
https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@0.1.36/site.min.js"
async defer>
</script>
<script nomodule
src="
https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@0.1.36/site.compat.min.js"
async defer>
</script>
<div class="frc-captcha"
data-sitekey="YOUR_SITEKEY_HERE">
</div>
<!-- Copy frc-captcha-response token into SoSci internal variable -->
<script type="text/javascript">
<!--
document.querySelector('.frc-captcha').addEventListener('frc:widget.complete', function(e) {
var input = document.getElementById("A702_01");
if (input) {
input.value = e.detail.response;
}
});
// -->
</script>
Replace YOUR_SITEKEY_HERE with your actual Sitekey from the Friendly Captcha dashboard. The second JavaScript listens for the moment the captcha puzzle is solved and copies the resulting token into the hidden form field created by your internal variable question: Replace A702_01 with the actual identifier of your internal variable.
STEP 3 Create the Internal Variable Question in SoSciSurvey
Set up the hidden storage field that transfers the captcha token to PHP
In SoSci Survey create a new question block and create a internal variable, go to: Fragenkatalog → Frage hinzufügen → Funktionale Bausteine → Interne Variablen
Then name the first item in the newly created internal variable. In this example we named it CAPT — this becomes the column header in your exported dataset.
This first variable now has an assigned variable identifier:
Variable identifier: A702_01
(or whatever SoSci assigns — check under Variablen-Übersicht)
⚠ Important: The internal variable question must be dragged onto the same survey PAGE as the captcha widget later. This is what causes SoSci to render a hidden <input> field in the HTML form, which JavaScript can then write the token into.
Page Layout After Step 3
Your survey page should now contain, in this order:
1. HTML-Code text element: widget loading scripts + captcha div + JavaScript token-copy script
2. Internal variable question (A702 / CAPT) — dragged onto this page
STEP 4 Add PHP Verification on the Next Page
Verify the token with Friendly Captcha's API and block bots
On the page immediately following your captcha page, add a PHP text element with the following code:
// Read the captcha token from the internal variable (submitted on previous page)
$captcha_response = value('A702_01');
// Send the token to Friendly Captcha's EU API for verification
$result = sendJSON(
'
https://eu.frcapi.com/api/v2/captcha/siteverify',
[
'response' => $captcha_response,
'sitekey' => 'YOUR_SITEKEY_HERE'
],
[
'X-API-Key' => 'YOUR_API_KEY_HERE'
]
);
// Block navigation if verification failed not possible to continue (klick next page)
if ($result['success'] == false) {
option('backbutton', false);
option('nextbutton', false);
}
Replace YOUR_SITEKEY_HERE and YOUR_API_KEY_HERE with your actual credentials from the Friendly Captcha dashboard. Replace A702_01 with the actual identifier of your internal variable.
⚠ Why the PHP goes on the NEXT page: SoSci executes PHP when building a page, before the user has submitted the form. So value('A702_01') can only be read after the form has been submitted — i.e., on the following page.
ℹ You can also paste your own PHP code in the if($result['success'] == false) {} block. The one above stops the page from showing the next or back button.
During Testing: Use Debug Mode
While testing, add these two lines at the end of your PHP block to inspect the values:
debug($captcha_response); // Should show a long token string starting with AQEA... or AQQA...
debug($result); // Should show [success][true] for a real person