Adding hCaptcha Spam Protection
This guide will help you add spam protection to your forms using hCaptcha. It includes:
- a tutorial for creating an Authorization Policy and adding it to your page
- an example of adding a regular form in a page (without form configuration) with the hcaptcha tags inside
- an example of protecting the page with the slug
/main-content - an example of using an invisble hCaptcha
- an example of using custom html attributes
Requirements
To follow this topic, you should be familiar with Authorization Policies, including how to add an Authorization Policy and associate it with a page.
Example 1: Regular form in a page (without form configuration)
This example shows how to add a regular form in a page (without form configuration) with the hcaptcha tags inside. This form posts to a page which has an authorization policy with the same content as in the example above.
app/authorization_policies/check_regular_hcaptcha_authorized.liquid
---
name: check_regular_hcaptcha_authorized
redirect_to: /unauthorized
flash_alert: Sorry
---
{{ params | hcaptcha }}
app/authorization_policies/check_authencity_token.liquid
---
name: check_authenticity_token
redirect_to: /unauthorized
flash_alert: Sorry
---
{{ context.csrf_request_valid }}
app/views/pages/regular_form_in_page.liquid
---
slug: regular_form_in_page
layout_name: 1col
---
<h1>Test hcaptcha in a regular form page.</h1>
<form action="/regular_page_post" method="post">
<input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}" />
{% spam_protection "hcaptcha" %}
<input type="submit" name="submit" value="Submit" />
</form>
app/views/pages/regular_page_post.liquid
---
slug: regular_page_post
layout_name: 1col
method: post
authorization_policies:
- check_regular_hcaptcha_authorized
- check_authenticity_token
---
Protected page
Example 2: Protect page with the slug /main-content
To protect the page with the slug /main-content, create two pages:
/main-content/content-protection
/main-content has an authorization policy with the same content as above, and uses redirect_to /content-protection (when the hcaptcha check fails). /content-protection has a regular form in it (no form configuration) with hcaptcha tags inside and posts to /main-content. This way main-content is hcaptcha protected by content-protection.
app/authorization_policies/check_authorized_for_content.liquid
---
name: check_authorized_for_content
redirect_to: /content-protection
flash_alert: Please solve the captcha correctly.
---
{{ params | hcaptcha }}
app/views/pages/main-content.liquid
---
slug: main-content
layout_name: 1col
method: post
authorization_policies:
- check_authorized_for_content
---
Protected content
app/views/pages/content-protection.liquid
---
slug: content-protection
layout_name: 1col
---
<h1>Please solve the captcha below to access the protected content.</h1>
<form action="/main-content" method="post">
<input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}" />
{% spam_protection "hcaptcha" %}
<input type="submit" name="submit" value="Submit" />
</form>
Example 3: Using an invisible hCaptcha
hCaptcha can be configured to run in the "invisible" mode. Invisible mode means no checkbox is used, and the challenge will be displayed when the user attempts to submit the form.
To use the invisible mode, you must add invisible: true to the spam_protection tag as below.
app/views/pages/form_with_captcha.liquid
---
slug: form_with_captcha
---
<form method="post" action="/protected-page">
<input name="title" value="" type="text" />
{% spam_protection 'hcaptcha', invisible: true %}
<input type="submit" class="hcaptcha-submit-button" name="submit" text="Submit" />
</form>
When using invisible mode, the submit button must have the class hcaptcha-submit-button.
To change this behavior, ensure there is no hcaptcha-submit-button element in the page, and override the default behavior with code similar to:
function customhCaptchaOnLoad() {
let element = document.querySelector('.my-customized-image');
if(element) {
element.onclick = hCaptchaOnClick;
}
}
document.addEventListener('DOMContentLoaded', function() {
customhCaptchaOnLoad();
});
The above code will use an element with the class my-customized-image as the trigger for form submission with hCaptcha verification.
Example 4: Using hCaptcha custom HTML attributes
You can use custom HTML attributes with the spam_protection tag to access additional hCaptcha functionality. Find an example below:
app/views/pages/page_with_captcha.liquid
---
slug: page_with_captcha
---
<form action="/submit_hcaptcha_endpoint" method="post" class="model-form" novalidate="novalidate">
<input name="title" value="Title" type="text" />
{% assign html_attrs = '{}' | parse_json %}
{% hash_assign html_attrs['data-size'] = 'compact' %}
{% hash_assign html_attrs['data-callback'] = 'someCallback' %}
{% spam_protection 'hcaptcha', html_attributes: html_attrs %}
<input type="submit" name="submit" value="Submit" />
</form>
Live example and source code
To play with the live example visit the sign-in-hcaptcha page.
Source code can be found on GitHub.