Shopify uses [hCaptcha](https://hcaptcha.com) to help prevent spam through customer, contact, and blog comment forms.

Initially, hCaptcha analyzes website visitor behavior to provide a score indicating the likelihood of the visitor being a bot, without requiring the visitor to solve an interactive challenge.

If the assessment result is suspicious enough, or if too many requests are made within a short period of time, then the visitor is redirected to the `/challenge` page to perform an interactive challenge for further assessment.

Merchants are able to [disable hCaptcha functionality](https://help.shopify.com/manual/online-store/setting-up/preferences#enable-or-disable-recaptcha-on-online-store) on the **Online Store** > **Preferences** page in the Shopify admin.

## How CAPTCHA is included in themes

The necessary code for the CAPTCHA functionality is included through the [`content_for_header` object](/docs/api/liquid/objects/content_for_header). This means that if a merchant has CAPTCHA enabled, but the `content_for_header` object isn't present, then the CAPTCHA functionality won't be present.

The CAPTCHA functionality is initialized based on the presence of customer, contact, and blog comment forms, and by default is triggered when the forms are interacted with. For example, the functionality is triggered when a user clicks a text field of an associated form.

These forms are identified based on the `action` attribute of the form, as well as specific input attributes:

<table>
  <thead>
    <tr>
      <th>Form type</th>
      <th>Form <code>action</code> attribute</th>
      <th>Input attributes (included on a single input)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Customer</td>
      <td>Contains <code>/account</code></td>
      <td>
        <p><code>name="form_type"</code></p>
        <p>One of the following, depending on the form:</p>
        <ul>
          <li>
            <code>value="customer_login"</code>
          </li>
          <li>
            <code>value="create_customer"</code>
          </li>
          <li>
            <code>value="recover_customer_password"</code>
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Contact</td>
      <td>Contains <code>/contact</code></td>
      <td>
        <p><code>name="form_type"</code></p>
        <p>One of the following, depending on the form:</p>
        <ul>
          <li>
            <code>value="contact"</code>
          </li>
          <li>
            <code>value="customer"</code>
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Blog</td>
      <td>Contains <code>/blogs</code></td>
      <td>
        <ul>
          <li>
            <code>name="form_type"</code>
          </li>
          <li>
            <code>value="new_comment"</code>
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

> Tip:
> The form `action` attribute and associated input attributes are output by default when using a relevant Liquid [form tag](/docs/api/liquid/tags/form). If your theme uses custom forms, then make sure that the above attributes are included so that your forms are compatible with CAPTCHA functionality.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="Example"></script>

<script type="text/plain" data-language="html">
<form action="/account/login" ...>
  <input type="hidden" name="form_type" value="customer_login">
  ...
</form>
</script>

</div>
</p>


In addition to triggering the CAPTCHA functionality on user interaction, a CAPTCHA logo is added to the bottom right corner of the page to notify visitors of the behavior analysis. You can opt to [show a text disclaimer](#show-a-text-disclaimer) with the form instead.

## Show a text disclaimer

If CAPTCHA is enabled and CAPTCHA has loaded, then the CAPTCHA logo appears in the bottom right corner of any associated pages. You can choose to show a text disclaimer with the form, rather than this logo.

To do this, you need to include the following code within any forms you wish to change this for:

```liquid

{{ "shopify.online_store.spam_detection.disclaimer_html" | t }}

```

## Advanced: Forcing CAPTCHA wire up to a form

> Caution:
> To keep your integration compatible with Shopify's form abuse protection mechanisms, avoid working directly with the underlying CAPTCHA libraries. For example, don't call methods on `window.hCaptcha`. Instead, use the following supported methods.

In some scenarios, it might be necessary to force CAPTCHA wire up to a form. For example, the form might be indirectly populated and submitted, so the default behavior of wiring CAPTCHA on user interaction never happens. In these cases, you have the following options:

### Wire up using a data attribute

Adding the `data-shopify-captcha` attribute with a value of `true` causes CAPTCHA to wire up to the form immediately when the page loads.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="Data attribute example (Liquid)"></script>

<script type="text/plain" data-language="liquid">

{%- form 'customer_login', data-shopify-captcha: "true" -%}

</script>

</div>
</p>


<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="Data attribute example (HTML)"></script>

<script type="text/plain" data-language="html">
<form data-shopify-captcha="true" action="/account/login" ...>
  <input type="hidden" name="form_type" value="customer_login">
  ...
</form>
</script>

</div>
</p>


### Wire up using JavaScript

Alternatively, CAPTCHA can be wired up to a form using JavaScript. `window.Shopify.captcha.protect` should be invoked with the form that you want to wire up as the first argument, and with an optional callback function as the second argument. If provided, the callback is invoked after CAPTCHA is ready.

This is primarily useful in cases where you programmatically manipulate and submit the form in response to other user action.

<p>
<div class="react-code-block" data-preset="basic">
<div class="react-code-block-preload ThemeMode-dim">
<div class="react-code-block-preload-bar basic-codeblock"></div>
<div class="react-code-block-preload-placeholder-container">
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>
<div class="react-code-block-preload-code-container">
<div class="react-code-block-preload-codeline-number"></div>
<div class="react-code-block-preload-codeline"></div>
</div>

</div>
</div>

<script data-option="title" data-value="JavaScript example"></script>

<script type="text/plain" data-language="javascript">
const myForm = document.querySelector('#my-form');
window.Shopify.captcha.protect(myForm, () => {
  myForm.elements["contact[email]"].value = 'test@example.com';
  myForm.submit();
});
</script>

</div>
</p>


## Verifying that hCaptcha is wired up

You can verify that hCaptcha is correctly wired to your form by using your browser's network dev tools while the form is being submitted.

1. Open dev tools on the **Network** tab.
2. Fill in and submit the form.
3. In the browser's dev tools, inspect the payload of the POST request to the server.
4. Ensure that the `h-captcha-response` field is present and contains data.

## Troubleshooting

- Ensure that your theme includes Liquid's [`content_for_header`](/docs/api/liquid/objects/content_for_header) object
in layouts that contain forms that require hCaptcha. Ensure that no code modifies or changes this object.

- If you want your form to be automatically wired up, ensure that its markup is correct, with the requisite `action` attribute and corresponding
`form_type` child input. For more information, refer to how [CAPTCHA is included in themes](#how-captcha-is-included-in-themes).

- By default, hCaptcha is initialized on the [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) event, but is only wired up when the user interacts with the form. If you're building or submitting forms programmatically or adding them to the DOM after the `DOMContentLoaded` event has been emitted, then you might need to use [`window.Shopify.captcha.protect`](#wire-up-using-javascript) to ensure that CAPTCHA executes correctly.

- Some third-party applications may block hCaptcha resources, or otherwise manipulate the DOM in ways that cause hCaptcha to not wire
up correctly. Such apps could be focused on improving page load metrics or managing GDPR consent. Consider
temporarily disabling such apps while you debug. Often the apps have ignore lists that enable you to fix the issue after it's identified.