CAPTCHA V1 GUIDE

Add an explicit challenge with accessible alternatives.

V1 is intended for flows that require visible human interaction. The server controls the provider policy and successful completion returns a one-time response token.

Maintained documentation4 sectionsAPI contract

Embed the form-associated widget

Place the custom element inside the protected form. The widget pauses native submission until verification succeeds and contributes the response using its name attribute.

html

<form method="post" action="/contact">
    <input name="email" type="email" required>
    <giws-captcha
        sitekey="YOUR_SITE_KEY"
        action="contact"
        name="giws-captcha-response"
        lang="en"
    ></giws-captcha>
    <button type="submit">Send</button>
</form>
<script src="https://captcha.giws.us/widget/v1.js" async defer></script>

Respect provider and accessibility policy

The site setting selects image or puzzle as the default visual provider. Users can still move to audio or accessible text without replacing the challenge envelope.

Use lang="ar" for Arabic and RTL rendering
Keep native focus indicators visible
Do not hide audio or accessible-text alternatives
Treat the provider attribute as a request, not an authorization decision

Handle completion and verify

Traditional forms can use the submitted field. SPA flows may listen for giws-captcha-success or configure a restricted global callback name.

javascript

document.querySelector('giws-captcha').addEventListener('giws-captcha-success', (event) => {
    const response = event.target.value;
    // Send response to your backend, then call POST /api/siteverify there.
});

Verify the response on your server

Content Security Policy

A strict host policy must allow the CAPTCHA origin for the loader and API, plus its protected image and audio assets.

script-src: https://captcha.giws.us
connect-src: https://captcha.giws.us
img-src: https://captcha.giws.us
media-src: https://captcha.giws.us