adding-hcaptcha-spam-protection.liquid

---
converter: markdown
metadata:
  title: Adding hCaptcha Spam Protection
  description: This guide will help you add spam protection to your forms using hCaptcha. 
---
This guide will help you add spam protection to your forms using [hCaptcha](https://www.hcaptcha.com/). 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](/developer-guide/integrations/adding-hcaptcha-spam-protection#example-1-regular-form-in-a-page-without-form-configuration) (without form configuration) with the hcaptcha tags inside
* [an example of protecting the page](/developer-guide/integrations/adding-hcaptcha-spam-protection#example-2-protect-page-with-the-slug-main-content) with the slug `/main-content`
* [an example of using an invisble hCaptcha](/developer-guide/integrations/adding-hcaptcha-spam-protection#example-3-using-an-invisible-hcaptcha)
* [an example of using custom html attributes](/developer-guide/integrations/adding-hcaptcha-spam-protection#example-4-using-hcaptcha-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.
* [Authorization Policy](/developer-guide/authorization-policy/authorization-policy)
* [Adding an Authorization Policy](/developer-guide/authorization-policy/adding-authorization-policy)

## 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

```liquid
{% raw %}
---
name: check_regular_hcaptcha_authorized
redirect_to: /unauthorized
flash_alert: Sorry
---
{{ params | hcaptcha }}
{% endraw %}
```

#### app/authorization_policies/check_authencity_token.liquid

```liquid
{% raw %}
---
name: check_authenticity_token
redirect_to: /unauthorized
flash_alert: Sorry
---
{{ context.csrf_request_valid }}
{% endraw %}
```

#### app/views/pages/regular_form_in_page.liquid

```liquid
{% raw %}
---
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>
{% endraw %}
```

#### app/views/pages/regular_page_post.liquid

```liquid
{% raw %}
---
slug: regular_page_post
layout_name: 1col
method: post
authorization_policies:
  - check_regular_hcaptcha_authorized
  - check_authenticity_token
---

Protected page
{% endraw %}
```

## 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

```liquid
{% raw %}
---
name: check_authorized_for_content
redirect_to: /content-protection
flash_alert: Please solve the captcha correctly.
---
{{ params | hcaptcha }}
{% endraw %}
```

#### app/views/pages/main-content.liquid

```liquid
{% raw %}
---
slug: main-content
layout_name: 1col
method: post
authorization_policies:
  - check_authorized_for_content
---

Protected content
{% endraw %}
```

#### app/views/pages/content-protection.liquid

```liquid
{% raw %}
---
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>
{% endraw %}
```

## 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

```liquid
{% raw %}
---
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>
{% endraw %}
```

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:

```javascript
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

```liquid
{% raw %}
---
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>
{% endraw %}
```

## Live example and source code
To play with the live example visit the [sign-in-hcaptcha](https://examples.platform-os.com/sign-in-hcaptcha) page.

[Source code](https://github.com/mdyd-dev/platformos-examples/tree/master/modules/sign_in_hcaptcha) can be found on GitHub.