ZapCaptcha Quickstart Guide

Protect your website with ZapCaptcha in four steps.

ZapCaptcha is a configurable, browser-based CAPTCHA system developed by QVLX Labs. It supports form submissions, custom button actions, multiple CAPTCHA challenges, and optional server-side integration.

You can get started with only JavaScript and HTML. A dedicated server integration is optional, but recommended when authoritative verification is required.

Quick Overview

Step	Action	Required
1	Load ZapCaptcha JavaScript	Yes
2	Add the CAPTCHA HTML	Yes
3	Connect the verification action	Yes
4	Configure security and appearance	Optional

Step 1 — Install ZapCaptcha

Add the following script near the end of your HTML document's <body>.

<script
  type="module"
  src="https://zapcaptcha.com/zapcaptcha.js">
</script>

This is the only required external dependency for the standard browser-based integration.

Recommended: Handle Disabled JavaScript

Add this inside your HTML <head>:

<noscript>
  <meta
    http-equiv="refresh"
    content="0; url=/no-js.html">
</noscript>

Replace /no-js.html with an appropriate page explaining that JavaScript is required.

Security note: Browser-only controls cannot securely enforce a server-side operation when JavaScript is disabled or bypassed. Protect important server endpoints independently.

Optional: Fallback Stylesheet

The supplied integration guide also recommends:

<noscript>
  <link
    rel="stylesheet"
    href="https://zapcaptcha.com/zapcaptcha.css">
</noscript>

This is an optional fallback and is not required for the normal JavaScript integration.

Step 2 — Add a CAPTCHA to Your Page

Choose the integration pattern appropriate for your application.

Option A — Protect a Form Submission

Use this method for:

Contact forms
Registration forms
Feedback forms
Other form submissions

Add the following HTML:

<form id="contactForm" action="/submit" method="POST">

  <input
    type="text"
    name="message"
    placeholder="Your message"
    required>

  <div
    class="zcaptcha-box"
    data-target-id="submitBtn"
    data-zcap-timeout="20">
  </div>

  <button
    type="submit"
    class="zapcaptcha-button"
    id="submitBtn"
    disabled>
    Submit
  </button>

</form>

Understanding the Attributes

Attribute	Purpose
`class="zcaptcha-box"`	Identifies the CAPTCHA container
`data-target-id`	Associates the CAPTCHA with the target element
`data-zcap-timeout`	Configures the CAPTCHA timeout
`class="zapcaptcha-button"`	Identifies the protected button
`disabled`	Initially disables the button until enabled by ZapCaptcha

Important: The data-target-id value must match the protected button's id.

In this example, both use submitBtn.

Option B — Protect a Custom Button Action

Use this method when a button executes JavaScript instead of submitting a form.

<div class="example-box">

  <div
    class="zcaptcha-box"
    data-target-id="verifyBtn"
    data-zcap-timeout="20">
  </div>

  <button
    type="button"
    class="zapcaptcha-button"
    id="verifyBtn"
    disabled>
    Verify Me
  </button>

  <div class="inline-result"></div>

</div>

After successful verification, the button can execute a custom callback.

Step 3 — Connect JavaScript Verification

ZapCaptcha provides the following verification method:

window.ZapCaptcha.verify(trigger, successCallback);

Argument	Description
`trigger`	The button or element associated with the challenge
`successCallback`	Function executed when verification succeeds

Form Submission Example

For the form from Step 2, add:

<script>
window.addEventListener("DOMContentLoaded", () => {
  const form = document.getElementById("contactForm");
  const button = document.getElementById("submitBtn");

  if (!form || !button) return;

  button.addEventListener("click", (event) => {
    event.preventDefault();

    if (!form.reportValidity()) return;

    window.ZapCaptcha?.verify(button, () => {
      form.submit();
    });
  });
});
</script>

How It Works

The user completes the form.
The user clicks Submit.
The normal button action is intercepted.
ZapCaptcha evaluates the verification challenge.
The success callback submits the form.

Note: form.submit() submits the form programmatically. It does not independently prove verification to your backend. Use a supported server-side verification workflow when the server must enforce CAPTCHA success.

Custom Button Example

For the verifyBtn example:

<script>
window.addEventListener("DOMContentLoaded", () => {
  const button = document.getElementById("verifyBtn");

  if (!button) return;

  button.addEventListener("click", (event) => {
    event.preventDefault();

    window.ZapCaptcha?.verify(button, () => {
      const output = document.querySelector(".inline-result");

      if (output) {
        output.textContent = "Human verified!";
      }
    });
  });
});
</script>

The success callback can be replaced with your own application logic.

Step 4 — Configure ZapCaptcha

ZapCaptcha supports configuration through HTML meta tags.

Place the configuration inside your document's <head>.

Example: Enable All Security Features

<meta
  name="zap-flags"
  content="allsec = true">

This enables the collection of security countermeasures represented by allsec.

Override Individual Settings

You can combine multiple configuration options:

<meta
  name="zap-flags"
  content="allsec = true, lockoutsEnabled = false">

In this example, all security options are enabled while client-side lockouts are disabled.

Common Configuration Flags

Flag	Default	Purpose
`viewportConfined`	`true`	Restrict CAPTCHA challenge placement to the viewport
`canvasMode`	`true`	Use Canvas rendering
`lockoutsEnabled`	`true`	Enable client-side lockouts
`sessionLock`	`true`	Store lockout state in session storage
`cookieLock`	`true`	Store lockout state in cookies
`localLock`	`false`	Persist lockout state in local storage
`softLock`	`false`	Disable protected actions rather than using a hard lockout
`serverMode`	`false`	Enable server-integrated mode
`serverLock`	`false`	Allow server-authoritative lockout decisions when configured
`clickDelay`	`false`	Introduce randomized click delays
`spawnDelay`	`false`	Introduce randomized challenge appearance delays
`frictionLess`	`false`	Enable frictionless CAPTCHA capabilities
`debugMessages`	`false`	Display diagnostic messages

Example: Custom Security Configuration

<meta
  name="zap-flags"
  content="clickBlockEnforcement = true, canvasSpoofingCheck = true">

This enables two selected protections without activating the full allsec configuration.

Additional Security Flags

ZapCaptcha also documents the following optional protections:

Flag	Purpose
`checksumJS`	JavaScript integrity checking
`checksumCSS`	CSS integrity checking
`functionTamperCheck`	Detect selected modifications to core functions
`canvasSpoofingCheck`	Detect selected Canvas manipulation patterns
`headlessBrowserCheck`	Identify selected headless browser environments
`cssOverrideDetection`	Detect selected CSS changes
`iframeEmbedCheck`	Detect execution inside an iframe
`iframeInjectCheck`	Detect injected iframe elements
`torCheck`	Identify selected Tor-related signals
`vpnCheck`	Identify selected VPN-related signals
`lockShadow`	Apply Shadow DOM-related protections
`monkeyPatching`	Modify selected DOM creation functions
`devtoolsCheck`	Detect selected developer-tool activity

These features may affect compatibility and legitimate users. Test the configuration before production deployment.

Customizing CAPTCHA Appearance and Behavior

Timeout

Configure the timeout with:

<div
  class="zcaptcha-box"
  data-target-id="submitBtn"
  data-zcap-timeout="120">
</div>

The documented default is 20 seconds.

Compact Mode

For layouts with limited space:

<div
  class="zcaptcha-box"
  data-target-id="submitBtn"
  data-size="compact">
</div>

Compact mode is useful for narrower containers.

Frictionless Mode

First enable frictionless functionality:

<meta
  name="zap-flags"
  content="frictionLess = true">

Then enable it on an individual CAPTCHA container:

<div
  class="zcaptcha-box"
  data-target-id="submitBtn"
  data-zcap-frictionless="1">
</div>

Frictionless functionality is disabled by default.

Using Multiple CAPTCHAs

You can add multiple CAPTCHA containers to a single page.

Each protected button must have a unique identifier that matches its CAPTCHA container.

HTML

<form id="formOne" action="/submit-one" method="POST">

  <div
    class="zcaptcha-box"
    data-target-id="buttonOne"
    data-zcap-timeout="30">
  </div>

  <button
    type="submit"
    id="buttonOne"
    class="zapcaptcha-button"
    disabled>
    Submit First
  </button>

</form>

<form id="formTwo" action="/submit-two" method="POST">

  <div
    class="zcaptcha-box"
    data-target-id="buttonTwo"
    data-zcap-timeout="30">
  </div>

  <button
    type="submit"
    id="buttonTwo"
    class="zapcaptcha-button"
    disabled>
    Submit Second
  </button>

</form>

JavaScript

window.addEventListener("DOMContentLoaded", () => {
  document.querySelectorAll(".zcaptcha-box").forEach(box => {
    const targetId = box.getAttribute("data-target-id");

    if (!targetId) return;

    const button = document.getElementById(targetId);

    if (!button || button.dataset.bound) return;

    button.dataset.bound = "true";

    button.addEventListener("click", event => {
      event.preventDefault();

      const form = button.closest("form");

      if (form && !form.reportValidity()) return;

      window.ZapCaptcha?.verify(button, () => {
        if (form) form.submit();
      });
    });
  });
});

Each button uses its associated CAPTCHA challenge.

Optional — Enable Integrity Verification

ZapCaptcha documents SHA-384 integrity checks for its JavaScript and stylesheet resources.

To configure them, provide expected hashes through HTML meta tags.

JavaScript Integrity

<meta
  name="zap-js-integrity"
  content="sha384-JS_HASH_HERE">

CSS Integrity

<meta
  name="zap-css-integrity"
  content="sha384-CSS_HASH_HERE">

Then enable the corresponding checks:

<meta
  name="zap-flags"
  content="checksumJS = true, checksumCSS = true">

Replace the placeholders with current, verified SHA-384 values in the format required by ZapCaptcha.

These values must match the actual resources being loaded.

Important: The supplied guide contains published resource hashes, but integrity values should be verified against the exact current files before deployment rather than assumed to remain valid after updates.

Optional — Server Integration

ZapCaptcha can run entirely in the browser, but browser-side verification and server-enforced verification provide different security guarantees.

Browser-Only Mode

The default configuration is:

<meta
  name="zap-flags"
  content="serverMode = false">

This mode supports client-side CAPTCHA behavior without requiring a dedicated verification server.

It is suitable for client-side interaction gating where the application's security requirements permit it.

Server-Integrated Mode

Enable the documented server mode:

<meta
  name="zap-flags"
  content="serverMode = true">

Additional server configuration is required.

Server mode is intended for applications requiring stronger server-side trust decisions.

The server protocol, required endpoints, and validation procedures are separate from this quickstart and must be implemented according to the server integration documentation.

Do not assume that setting serverMode = true alone protects a backend endpoint.

Troubleshooting

CAPTCHA Does Not Appear

Check that:

The ZapCaptcha script is loading.
JavaScript is enabled.
The CAPTCHA container uses class="zcaptcha-box".
The target button exists.
data-target-id matches the button's id.
Browser security policies permit the required resources.

Button Remains Disabled

The supplied guide recommends allowing ZapCaptcha to manage the initially disabled button.

If the button never becomes available, check for initialization errors, resource loading problems, or active lockout settings.

Verification Callback Does Not Run

Ensure that the button is correctly associated with its CAPTCHA and that ZapCaptcha.verify() is called from the intended event handler.

The callback runs after successful verification.

Form Does Not Submit

Check that:

The form exists.
Its required fields are valid.
The success callback calls the correct form.
The form's destination accepts the request.

CAPTCHA Is Difficult to Use on Mobile

Try compact mode:

data-size="compact"

Also consider retaining the default viewport-confined behavior.

Users Are Unexpectedly Locked Out

Review security settings such as:

lockoutsEnabled
sessionLock
cookieLock
localLock

Some automated detection signals can produce false positives.

Content Security Policy Errors

If your website uses CSP, ensure its policy permits the required ZapCaptcha scripts, styles, and associated resources.

Do not broadly enable unsafe script execution merely to resolve a configuration problem.

Deployment Checklist

Before publishing your integration, verify the following:

You're Ready

You've now configured ZapCaptcha for a form submission or custom action.

You can expand your integration with multiple CAPTCHA challenges, customized timeout settings, frictionless verification, integrity checks, and additional security controls.

For applications protecting sensitive operations, use a properly implemented server-side verification process rather than relying exclusively on browser-side restrictions.

ZapCaptcha by QVLX Labs — configurable CAPTCHA protection for modern websites.