Connect Google reCAPTCHA

Lesson 9 / 22 · Commentail 1.3.2

The built-in arithmetic challenge needs no provider account. Google is optional. This integration requires reCAPTCHA v2 checkbox, not v3 or a different Enterprise integration.

Obtain matching keys

Open the reCAPTCHA console, create a dedicated practice registration, select v2 checkbox and add your actual test hostname without a scheme or path. For local practice use a provider-supported localhost setup; do not treat 127.0.0.1 and localhost as interchangeable. The Wagtail Site must match the address used to open the page.

Store site key and secret key as CAPTCHA_SITE_KEY and CAPTCHA_SECRET_KEY using lesson 5. A visible site key is expected; only the server reads the secret key.

Select the backend

Merge these fields into the existing COMMENTAIL["default"], retaining other options:

import os

# Merge into the existing COMMENTAIL["default"] dictionary.
COMMENTAIL = {
    "default": {
        "CAPTCHA_BACKEND": "commentail.captcha_providers.GoogleRecaptcha",
        "CAPTCHA_OPTIONS": {
            "site_key": os.environ["CAPTCHA_SITE_KEY"],
            "secret_key": os.environ["CAPTCHA_SECRET_KEY"],
            "timeout": 3,
        },
    },
}

Both keys must belong to the same v2 registration. The server timeout is 3 seconds; the accepted range is 1–10. Restart the website and run python manage.py check. Ensure {% commentail_js %} is loaded. Do not add a duplicate Google script: Commentail loads the widget when required.

Test a new guest

Use a fresh private session. Adaptive mode can exempt a previously confirmed guest. To require every guest to solve a challenge, set GUEST_CAPTCHA_MODE to "always" in default, then choose your intended policy after testing.

Test successful submission, missing proof, replying and an expired check. Enhanced-form errors should preserve the draft. The server verifies hostname too: a different domain's proof must not pass.

Required external challenges need JavaScript. There is no email-only or moderation-queue bypass. A Google outage does not automatically switch to arithmetic. Investigate loading failures rather than disabling verification.

If CSP blocks the widget, allow required sources using the official documentation, retaining the rest of your policy. Explain external browser requests in the site's privacy information. To return to arithmetic, set CAPTCHA_BACKEND to None, remove its options and restart; earlier tasks become invalid. Remove only the dedicated practice registration when the experiment is finished.

Related lessons

• 5. Environment variables without key confusion
• 10. Connect Yandex SmartCaptcha
• 11. Word rules, CSV and spam protection

Related documentation

• Callbacks
• Security-and-privacy