Back to Documentation
Widget Guide

Widget Guide

Configure and customize the ECURTIY verification widget for your website.

Quick Start

Add these two elements to your HTML to get started:

<!-- Widget container -->
<div id="ecurtiy-widget"></div>

<!-- Widget script -->
<script
  src="https://your-domain.com/widget/ecurtiy.js"
  data-site-key="eck_live_your_site_key"
  async defer>
</script>

Widget Modes

Checkbox

Classic click-to-verify checkbox. PoW runs in the background.

Best for:General forms, login pages, sign-ups
mode: "checkbox"

Slider

Drag-to-verify slider for higher security interactions.

Best for:Payment forms, sensitive actions, high-value transactions
mode: "slider"

Auto

Starts with checkbox, falls back to slider for suspicious behavior.

Best for:Adaptive security needs, mixed traffic
mode: "auto"

Manual Initialization

For more control, initialize the widget programmatically:

<div id="ecurtiy-widget"></div>

<script src="https://your-domain.com/widget/ecurtiy.js" async></script>

<script>
  // Wait for widget to load
  window.addEventListener('ecurtiy:ready', function() {
    ecurtiy.render('#ecurtiy-widget', {
      siteKey: 'eck_live_your_site_key',
      mode: 'checkbox',
      callback: function(token) {
        console.log('Verification successful:', token);
        // Send token to your server
      },
      errorCallback: function(error) {
        console.error('Verification failed:', error);
      },
      expiredCallback: function() {
        console.log('Token expired, please verify again');
      }
    });
  });
</script>

Configuration Options

OptionTypeRequiredDescription
siteKeystring
Required
Your site's public key (eck_live_...)
modestringOptionalWidget mode: 'checkbox', 'slider', or 'auto'. Default: site setting
callbackfunctionOptionalCalled with token on successful verification
errorCallbackfunctionOptionalCalled with error object on failure
expiredCallbackfunctionOptionalCalled when verification token expires

Widget Appearance

Light Theme

Clean, professional widget design that fits most websites

I'm not a robot

Data Attributes

Configure the widget using data attributes for zero-JavaScript setup:

<!-- Auto-render with data attributes -->
<div
  data-ecurtiy-sitekey="eck_live_your_site_key"
  data-ecurtiy-mode="checkbox"
  data-ecurtiy-callback="onVerify"
></div>

<script>
  function onVerify(token) {
    // Handle successful verification
  }
</script>

Form Integration

The widget automatically integrates with forms, blocking submission until verified:

<form action="/submit" method="POST">
  <input type="text" name="email" placeholder="Email" />

  <!-- Widget creates a hidden input with the token -->
  <div id="ecurtiy-widget"></div>

  <!-- Button is disabled until verification -->
  <button type="submit">Submit</button>
</form>

<script
  src="https://your-domain.com/widget/ecurtiy.js"
  data-site-key="eck_live_your_site_key"
  async defer>
</script>

The widget adds a hidden input named ecurtiy-token to the form.

Global API

ecurtiy.render(container, options)

Create a new widget instance in the specified container

ecurtiy.getResponse(widgetId)

Get the verification token for a widget

ecurtiy.reset(widgetId)

Reset a widget to its initial state

ecurtiy.version

Get the current widget version string

React Integration

Use the widget in React applications:

'use client'

import { useEffect, useRef } from 'react'

export function EcurtiyWidget({ siteKey, onVerify }) {
  const containerRef = useRef(null)

  useEffect(() => {
    if (!containerRef.current) return

    // Load script if not already loaded
    if (!window.ecurtiy) {
      const script = document.createElement('script')
      script.src = 'https://your-domain.com/widget/ecurtiy.js'
      script.async = true
      script.onload = () => renderWidget()
      document.body.appendChild(script)
    } else {
      renderWidget()
    }

    function renderWidget() {
      window.ecurtiy.render(containerRef.current, {
        siteKey,
        callback: onVerify
      })
    }

    return () => {
      // Cleanup if needed
    }
  }, [siteKey, onVerify])

  return <div ref={containerRef} />
}

Troubleshooting

Widget not appearing

  • • Check that the container element exists
  • • Verify the site key is correct
  • • Check browser console for errors
  • • Ensure the site key matches your site configuration

Verification failing

  • • Check if the site is active in the dashboard
  • • Verify monthly quota hasn't been exceeded
  • • Ensure challenges aren't expiring (5 min TTL)
  • • Check for network issues blocking API calls

Token validation errors

  • • Tokens expire after 5 minutes
  • • Tokens can only be used once
  • • Verify you're using the correct secret key
API ReferenceGetting Started