Welcome to Django AllCaptcha’s documentation!¶
This package allows you to easily integrate captcha services in your Django project.
Currently, it supports:
HCaptcha
Invisible HCaptcha
Recaptcha V2 Checkbox
Invisible Recaptcha V2
Recaptcha V3
Installation¶
First, install the package using pip:
pip install django-allcaptcha
Then, add allcaptcha to your Django INSTALLED_APPS list.
django-allcaptcha ships with Javascript. You need to run collectstatic when deploying to production.
By default, Hcaptcha will be used.
Set CAPTCHA_PROVIDER in your settings to override this.
For Hcaptcha, set your keys:
HCAPTCHA_SECRET_KEY
HCAPTCHA_SITE_KEY
For Recaptcha V2:
RECAPTCHA_V2_SECRET_KEY
RECAPTCHA_V2_SITE_KEY
And Recaptcha V3:
RECAPTCHA_V3_SECRET_KEY
RECAPTCHA_V3_SITE_KEY
For all available options, see Settings
Tutorial¶
Learn how to quickly setup allcaptcha in your Django templates.
First, you need to a Form that inherits from CaptchaFormMixin:
from django import forms
from allcaptcha.mixins import CaptchaFormMixin
class MySecureForm(CaptchaFormMixin, forms.Form)
email = forms.EmailField()
Then, you’re simply going to instantiate and include the form instance in your template context as usual.
In your template, you need to make sure you include the bundled Javascript like so:
{{ form.media.js }}
You should preferably include this right before the closing body tag after
all other HTML elements have been rendered.
In your form tag, you need to render the Captcha challenge:
{% load allcaptcha_tags %}
<form method="post" action=".">
{% csrf_token %}
{{ form }}
{% render_challenge %}
<button type="submit">Send</button>
</form>
The render_challenge template tag will render a visible Hcaptcha or
Recapptcha V2 challenge by default.
If you want to render an invisible challenge instead, do this:
{% load allcaptcha_tags %}
<form method="post" action=".">
{% csrf_token %}
{{ form }}
{% render_challenge "invisible" "Submit" %}
</form>
This will render a button that will trigger the invisible challenge on click.
The text on this button will read Submit.
Manual validation¶
Instead of using the CaptchaFormMixin, you can manually validate any
challenge response by calling the valid_response function:
from allcaptcha.utils import valid_response
success = valid_response("my-challenge-response")
This function will return either True or False depending on whether the response was valid or not.
Manual rendering¶
The steps above will allow to quickly integrate captcha into any Form.
However, you might want to manually render your challenges and call your own Javascript functions upon challenge completion.
In that case, take a look at the Template Tags reference to see all the available templates that will allow you to render your own HTML elements to trigger challenges.
Settings¶
django-allcaptcha comes with several settings.
Some come with sane defaults while others need to be set manually.
PROVIDER
Type: str
Default: hcaptcha
The provider to activate.
Can be one of the following:
hcaptcha
recaptcha
CAPTCHA_CHALLENGE_THEME
Type: str
Default: light
Specify either dark or light theme when rendering the challenge.
CAPTCHA_CHALLENGE_SIZE
Type: str
Default normal
Render either a normal or compact sized challenge widget.
HCaptcha specific settings¶
HCAPTCHA_URL
Type: str
Default: https://hcaptcha.com/siteverify
The URL where HCaptcha challenge tokens will be sent for verification.
HCAPTCHA_SECRET_KEY
Type: str
Default: None
Your secret key.
HCAPTCHA_SITE_KEY
Type: str
Default: None
Your site key.
HCAPTCHA_JS
HCAPTCHA_JS_CALLBACK
Type: str
Default: onHcaptchaSubmit
The callback function to execute after the user completes the invisible challenge.
Recaptcha specific settings¶
*RECAPTCHA_URL
Type: str
Default: https://www.google.com/recaptcha/api/siteverify
The URL where ReCaptcha challenge tokens will be sent for verification.
RECAPTCHA_V2_SECRET_KEY
Type: str
Default: None
Your V2 secret key.
RECAPTCHA_V2_SITE_KEY
Type: str
Default: None
Your V2 site key.
RECAPTCHA_V3_SECRET_KEY
Type: str
Default: None
Your V3 secret key.
RECAPTCHA_V3_SITE_KEY
Type: str
Default: None
Your V3 site key.
RECAPTCHA_JS
Type: str Default: https://www.google.com/recaptcha/api.js
The Javascript file containing Recaptcha APIs.
RECAPTCHA_JS_CALLBACK
Type: str
Default: onRecaptchaSubmit
The callback function to execute after the user completes the invisible or V3 challenge.
RECAPTCHA_VERSION
Type: int
Default: 2
The version of Recaptcha to use.
RECAPTCHA_MIN_SCORE
Type: float
Default: 0.6
The minimum score for a Recaptcha V3 challenge to be considered successful.