Skip to main content

Migration from FriendlyCaptcha

This guide helps you migrate from FriendlyCaptcha (proof-of-work widget, often via friendly-challenge) to MTCaptcha using the standard mtcaptchaConfig + widget + CheckToken flow.

Why migrate from FriendlyCaptcha​

  • Privacy and GDPR alignment: MTCaptcha’s documented privacy posture supports teams standardizing vendor data handling. See Privacy GDPR Compliance.
  • WCAG 2.1 AAA accessibility: Move to a CAPTCHA stack with published accessibility conformance materials. See Accessibility Compliance.
  • Global reliability, including China: FriendlyCaptcha traffic may depend on third-party CDNs and regional routing; MTCaptcha documents mainland China delivery. See Works in China.

Migration at a glance​

FriendlyCaptchaMTCaptcha
Client scriptE.g. https://cdn.jsdelivr.net/npm/friendly-challenge/widget.module.min.js (module) or your bundler importhttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget class.frc-captcha (or framework wrapper around FriendlyCaptcha).mtcaptcha (<div class="mtcaptcha"></div>)
Token nameTypically frc-captcha-solution (hidden field / solution string)mtcaptcha-verifiedtoken
Backend APIPOST https://api.friendlycaptcha.com/api/v1/siteverify (hosted); or your self-hosted verify endpointGET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Server-side verification only

Never expose your MTCaptcha PrivateKey in frontend bundles. Perform CheckToken only on the server.

Step 1: Replace client-side script and widget​

<!-- Remove [FriendlyCaptcha] -->
<script type="module" src="https://cdn.jsdelivr.net/npm/friendly-challenge/widget.module.min.js" async defer></script>
<div class="frc-captcha" data-sitekey="YOUR_FRIENDLYCAPTCHA_SITE_KEY"></div>

<!-- Add [MTCaptcha] -->
<script>
  var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" };
</script>
<script src="https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js" async defer></script>
<div class="mtcaptcha"></div>
Load order

Define mtcaptchaConfig with "sitekey": "YOUR_SITEKEY" before loading mtcaptcha.min.js.

If you initialized FriendlyCaptcha from JavaScript (not static HTML), remove that bootstrap and rely on MTCaptcha’s anchor div or explicit render.

Step 2: Update server-side verification​

Replace FriendlyCaptcha siteverify (or your self-hosted verifier) with:

GET https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=YOUR_PRIVATEKEY&token=VERIFIED_TOKEN

Use the form POST field mtcaptcha-verifiedtoken as token.

Token lifetime and single use

Validate tokens promptly. A second CheckToken on the same value may fail. See Validate Token (With Private Key).

For locked-down egress, use https://service2.mtcaptcha.com/mtcv1/api/checktoken as described in that guide.

Troubleshooting​

SymptomWhat to check
PoW widget still loadingEnsure FriendlyCaptcha module imports and <div class="frc-captcha"> are fully removed.
Wrong field on serverReplace frc-captcha-solution parsing with mtcaptcha-verifiedtoken.
CSP blocksAllow https://service.mtcaptcha.com for script (and service2 if applicable).
High client CPU from old PoWUsers should no longer pay proof-of-work cost after you remove FriendlyCaptcha.
token-expired / invalid-tokenStale token, double submit, or clock skew; refresh widget and retry once.

Further reading​

Post-Migration Checklist​

  • Removed FriendlyCaptcha assets and server verification endpoints.
  • mtcaptchaConfig uses "sitekey": "YOUR_SITEKEY" before mtcaptcha.min.js.
  • Backend reads mtcaptcha-verifiedtoken and calls https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Load, interaction, and conversion metrics compared before/after (PoW vs MTCaptcha).
  • CSP/network rules updated.