1Django reCAPTCHA 2================ 3**Django reCAPTCHA form field/widget integration app.** 4 5.. image:: https://travis-ci.org/praekelt/django-recaptcha.svg?branch=develop 6 :target: https://travis-ci.org/praekelt/django-recaptcha 7.. image:: https://coveralls.io/repos/github/praekelt/django-recaptcha/badge.svg?branch=develop 8 :target: https://coveralls.io/github/praekelt/django-recaptcha?branch=develop 9.. image:: https://badge.fury.io/py/django-recaptcha.svg 10 :target: https://badge.fury.io/py/django-recaptcha 11.. image:: https://img.shields.io/pypi/pyversions/django-recaptcha.svg 12 :target: https://pypi.python.org/pypi/django-recaptcha 13.. image:: https://img.shields.io/pypi/djversions/django-recaptcha.svg 14 :target: https://pypi.python.org/pypi/django-recaptcha 15 16.. contents:: Contents 17 :depth: 5 18 19.. note:: 20 django-recaptcha supports Google reCAPTCHA V2 - Checkbox (Default), Google reCAPTCHA V2 - Invisible and Google reCAPTCHA V3 please look at the widgets section for more information. 21 22 Django reCAPTCHA uses a modified version of the `Python reCAPTCHA client <http://pypi.python.org/pypi/recaptcha-client>`_ which is included in the package as ``client.py``. 23 24Requirements 25------------ 26 27Tested with: 28 29* Python: 2.7, 3.5, 3.6, 3.7, 3.8 30* Django: 1.11, 2.0, 2.1, 2.2, 3.0 31 32 33.. note:: 34* Django 2.2 requires SQLite 3.8.3 35* Django 2.2 supports Python 3.5, 3.6, and 3.7. 36* Django 3.0 supports Python 3.6, 3.7 and 3.8. 37We highly recommend and only officially support the latest release of each series. 38 39 40Installation 41------------ 42 43#. `Sign up for reCAPTCHA <https://www.google.com/recaptcha/intro/index.html>`_. 44 45#. Install with ``pip install django-recaptcha``. 46 47#. Add ``'captcha'`` to your ``INSTALLED_APPS`` setting. 48 49 .. code-block:: python 50 51 INSTALLED_APPS = [ 52 ..., 53 'captcha', 54 ... 55 ] 56 57#. Add the Google reCAPTCHA keys generated in step 1 to your Django production settings with ``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``. Note that omitting these settings will default to a set of test keys refer to `Local Development and Functional Testing <Local Development and Functional Testing_>`_ for more information. 58 59 For example: 60 61 .. code-block:: python 62 63 RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123' 64 RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456' 65 66 These can also be specified per field by passing the ``public_key`` or 67 ``private_key`` parameters to ``ReCaptchaField`` - see field usage below. 68 69#. (OPTIONAL) If you require a proxy, add a ``RECAPTCHA_PROXY`` setting (dictionary of proxies), for example: 70 71 .. code-block:: python 72 73 RECAPTCHA_PROXY = {'http': 'http://127.0.0.1:8000', 'https': 'https://127.0.0.1:8000'} 74 75#. (OPTIONAL) In the event ``www.google.com`` is not accessible the ``RECAPTCHA_DOMAIN`` setting can be changed to ``www.recaptcha.net`` as per the `reCAPTCHA FAQ <https://developers.google.com/recaptcha/docs/faq#can-i-use-recaptcha-globally>`_: 76 77 .. code-block:: python 78 79 RECAPTCHA_DOMAIN = 'www.recaptcha.net' 80 81This will change the Google JavaScript api domain as well as the client side field verification domain. 82 83Usage 84----- 85 86Fields 87~~~~~~ 88 89The quickest way to add reCAPTCHA to a form is to use the included 90``ReCaptchaField`` field class. A ``ReCaptchaV2Checkbox`` will be rendered by default. For example: 91 92.. code-block:: python 93 94 from django import forms 95 from captcha.fields import ReCaptchaField 96 97 class FormWithCaptcha(forms.Form): 98 captcha = ReCaptchaField() 99 100 101To allow for runtime specification of keys you can optionally pass the 102``private_key`` or ``public_key`` parameters to the constructor. For example: 103 104.. code-block:: python 105 106 captcha = ReCaptchaField( 107 public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh', 108 private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs', 109 ) 110 111If specified, these parameters will be used instead of your reCAPTCHA project settings. 112 113Widgets 114~~~~~~~ 115 116There are three widgets that can be used with the ``ReCaptchaField`` class: 117 118 ``ReCaptchaV2Checkbox`` for `Google reCAPTCHA V2 - Checkbox <https://developers.google.com/recaptcha/docs/display>`_ 119 120 ``ReCaptchaV2Invisible`` for `Google reCAPTCHA V2 - Invisible <https://developers.google.com/recaptcha/docs/invisible>`_ 121 122 ``ReCaptchaV3`` for `Google reCAPTCHA V3 <https://developers.google.com/recaptcha/docs/v3>`_ 123 124To make use of widgets other than the default Google reCAPTCHA V2 - Checkbox widget, simply replace the ``ReCaptchaField`` widget. For example: 125 126.. code-block:: python 127 128 from django import forms 129 from captcha.fields import ReCaptchaField 130 from captcha.widgets import ReCaptchaV2Invisible 131 132 class FormWithCaptcha(forms.Form): 133 captcha = ReCaptchaField(widget=ReCaptchaV2Invisible) 134 135The reCAPTCHA widget supports several `data attributes 136<https://developers.google.com/recaptcha/docs/display#render_param>`_ that 137customize the behaviour of the widget, such as ``data-theme``, ``data-size``, etc. You can 138forward these options to the widget by passing an ``attrs`` parameter to the 139widget, containing a dictionary of options. For example: 140 141.. code-block:: python 142 143 captcha = fields.ReCaptchaField( 144 widget=widgets.ReCaptchaV2Checkbox( 145 attrs={ 146 'data-theme': 'dark', 147 'data-size': 'compact', 148 } 149 ) 150 ) 151 # The ReCaptchaV2Invisible widget 152 # ignores the "data-size" attribute in favor of 'data-size="invisible"' 153 154The reCAPTCHA api supports several `paramaters 155<https://developers.google.com/recaptcha/docs/display#js_param>`_. To customise 156the paramaters that get sent along pass an ``api_params`` paramater to the 157widget, containing a dictionary of options. For example: 158 159.. code-block:: python 160 161 captcha = fields.ReCaptchaField( 162 widget=widgets.ReCaptchaV2Checkbox( 163 api_params={'hl': 'cl', 'onload': 'onLoadFunc'} 164 ) 165 ) 166 # The dictionary is urlencoded and appended to the reCAPTCHA api url. 167 168By default, the widgets provided only supports a single form with a single widget on each page. 169 170The language can be set with the 'h1' parameter, look at `language codes 171<https://developers.google.com/recaptcha/docs/language>`_ for the language code options. Note that translations need to be added to this package for the errors to be shown correctly. Currently the package has error translations for the following language codes: es, fr, nl, pl, pt_BR, ru, zh_CN, zh_TW 172 173However, the JavaScript used by the widgets can easily be overridden in the templates. 174 175The templates are located in: 176 177 ``captcha/includes/js_v2_checkbox.html`` for overriding the reCAPTCHA V2 - Checkbox template 178 179 ``captcha/includes/js_v2_invisible.html`` for overriding the reCAPTCHA V2 - Invisible template 180 181 ``captcha/includes/js_v3.html`` for overriding the reCAPTCHA V3 template 182 183 For more information about overriding templates look at `Django's template override <https://docs.djangoproject.com/en/2.1/howto/overriding-templates/>`_ 184 185reCAPTCHA v3 Score 186~~~~~~~~~~~~~~~~~~ 187 188As of version 3, reCAPTCHA also returns a score value. This can be used to determine the likelihood of the page interaction being a bot. See the Google `documentation <https://developers.google.com/recaptcha/docs/v3#score>`_ for more details. 189 190To set a project wide score limit use the ``RECAPTCHA_REQUIRED_SCORE`` setting. 191 192 For example: 193 194 .. code-block:: python 195 196 RECAPTCHA_REQUIRED_SCORE = 0.85 197 198For per field, runtime, specification the attribute can also be passed to the widget: 199 200 .. code-block:: python 201 202 captcha = fields.ReCaptchaField( 203 widget=ReCaptchaV3( 204 attrs={ 205 'required_score':0.85, 206 ... 207 } 208 ) 209 ) 210 211In the event the score does not meet the requirements, the field validation will fail as expected and an error message will be logged. 212 213Local Development and Functional Testing 214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 215 216Google provides test keys which are set as the default for ``RECAPTCHA_PUBLIC_KEY`` and ``RECAPTCHA_PRIVATE_KEY``. These cannot be used in production since they always validate to true and a warning will be shown on the reCAPTCHA. 217 218To bypass the security check that prevents the test keys from being used unknowingly add ``SILENCED_SYSTEM_CHECKS = [..., 'captcha.recaptcha_test_key_error', ...]`` to your settings, here is an example: 219 220 .. code-block:: python 221 222 SILENCED_SYSTEM_CHECKS = ['captcha.recaptcha_test_key_error'] 223 224Credits 225------- 226Inspired Marco Fucci's blogpost titled `Integrating reCAPTCHA with Django 227<http://www.marcofucci.com/tumblelog/26/jul/2009/integrating-recaptcha-with-django>`_ 228 229 230``client.py`` taken from `recaptcha-client 231<http://pypi.python.org/pypi/recaptcha-client>`_ licenced MIT/X11 by Mike 232Crawford. 233 234reCAPTCHA copyright 2012 Google. 235