# Google reCAPTCHA v2

Provides an easy-to-use anti-spam measure for forms. Supports I am not a Robot checkbox and Invisible reRECAPTCHA.

###

About the Plugin

Website Admin panel

Our reCAPTCHA module provides an easy-to-use interface to the Google reCAPTCHA v2 API.

Requires a Google account and reCAPTCHA API keys.

You may notice some errors in the console after implementing reCAPTCHA. This is due to Google's code and does not affect the functionality of the script. See this GitHub issue for more info.

###

Initializing

The required scripts are included automatically by the `form-email` module. This will handle reCAPTCHA functionality for any type of form that is submitted through our SMTP and mailchimp form handlers.

Each reCAPTCHA `<div>` is converted to a reCAPTCHA widget upon page load.

The following line must be declared in `scss/custom/components.scss`:

    @import "components/optional/forms";

This style component hides the invisible reCAPTCHA badge and makes other adjustments to spacing for reCAPTCHA widgets.

###

Obtain Site Key and Secret Key

Before you start, sign up for an API key pair for your site.

The key pair consists of a site key and secret key. The site key is used in the `<form>` HTML on your pages. The secret key authorizes communication between our form handlers and the reCAPTCHA server to verify the user's response. The secret key needs to be kept safe for security purposes.

###

Basic Usage

Add an empty `<div>` to your form where you would like the reCAPTCHA widget to appear. The `<div>` will be populated with the widget upon page load.

The widget will populate with the familiar "I am not a robot" mechanism.

- The div must have `data-recaptcha` attribute.
- The div must have `data-sitekey` with your reCAPTCHA site key as its value.
- Only one `[data-recaptcha]` may be initialized per form.

Obtain your `site key` from the Google reCAPTCHA admin panel where your keys are managed.

    <form action="/forms/mailchimp.php" data-form-email novalidate>
      <div class="form-row">
        <div class="col-12">
          <input type="email" class="form-control mb-2" placeholder="Email Address" name="email" required>
        </div>
        <div class="col-12">
          <div data-recaptcha data-sitekey="ENTER-YOUR-RECAPTCHA-SITE-KEY-HERE"></div>
        </div>
        <div class="col-12">
          <div class="d-none alert alert-success" role="alert" data-success-message>
            Thanks, a member of our team will be in touch shortly.
          </div>
          <div class="d-none alert alert-danger" role="alert" data-error-message>
            Please fill all fields correctly.
          </div>
          <button type="submit" class="btn btn-primary btn-loading btn-block" data-loading-text="Sending">
            <!-- Icon for loading animation -->
            <svg class="icon" width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><title>Icon For Loading</title><g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"><g><polygon points="0 0 24 0 24 24 0 24" opacity="0"></polygon></g><path d="M12,4 L12,6 C8.6862915,6 6,8.6862915 6,12 C6,15.3137085 8.6862915,18 12,18 C15.3137085,18 18,15.3137085 18,12 C18,10.9603196 17.7360885,9.96126435 17.2402578,9.07513926 L18.9856052,8.09853149 C19.6473536,9.28117708 20,10.6161442 20,12 C20,16.418278 16.418278,20 12,20 C7.581722,20 4,16.418278 4,12 C4,7.581722 7.581722,4 12,4 Z" fill="#000000" fill-rule="nonzero" transform="translate(12.000000, 12.000000) scale(-1, 1) translate(-12.000000, -12.000000) "></path></g></svg>
            <span>Subscribe</span>
          </button>
        </div>
      </div>
    </form>

###

Options

Options are provided to the reCAPTCHA API via data attributes on the `div[data-recaptcha]`.

Below are the options for the Checkbox widget.

Data attribute | Default | Description
--- | --- | ---
`data-sitekey` |  | Required. Place the site key obtained from your Google reCAPTCHA admin panel here.
`data-theme` | `light` | Accepts `"light"` or `"dark"`. Changes background shade of the widget.
`data-size` | `normal` | Accepts `"compact"` or `"normal"` for checkbox widget. Use `"invisible"` to create an invisible reCAPTCHA instance (see below).
`data-tabindex` | `0` | Optional. The tabindex of the widget. If other elements in your page use tabindex, it should be set to make user navigation easier.

Below are the options for Invisible Recaptcha.

Data attribute | Default | Description
--- | --- | ---
`data-sitekey` |  | Required. Place the site key obtained from your Google reCAPTCHA admin panel here.
`data-size` |  | Must be `"invisible"` for an invisible reCAPTCHA instance.
`data-badge` | `bottomright` | Accepts `"bottomright"`, `"bottomleft"`, `"inline"`. `inline` lets you position the badge using CSS.
`data-tabindex` | `0` | Optional. The tabindex of the widget. If other elements in your page use tabindex, it should be set to make user navigation easier.

###

Invisible reCAPTCHA

By default. invisible reCAPTCHA replaces the standard Checkbox widget with a small badge that floats at the edge of the window. The theme script will hide the badge to avoid interference on the page. This is to provide a frictionless experience and avoids cluttering the form with a widget.

When the user submits the form, they are presented with a challenge. Upon completing the challenge, the form is submitted.

When using Invisible reCAPTCHA You must provide a statement on your page notifying the user that the page uses Google reCAPTCHA. You must also provide a link to the Google Privacy Policy and Terms of Service.

###

Server-side Verification

The reCAPTCHA response from the user must also be verified on the server at form submission time. This functionality is handled in our supplied SMTP and MailChimp form handlers.

Simply copy your reCAPTCHA secret key into the provided form handler configuration to enable server-side verification.