@pimred/whcaptcha v0.5.0

React Client for WHCaptcha

Install

npm install --save @pimred/whcaptcha

Requirements

• configurationId: ID of the configuration from initial setup
• sessionString: ID that is unique per user and per submission (optional)
  If no sessionString is passed it will be created automatically and stores in the Browser's session storage

Usage

Minimal example

import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const { checkCaptcha, componentProps } = useWHCaptcha({ configurationId })

  ...

  const onSubmit = async () => {
    const captchaIsCorrect = await checkCaptcha()
    if (captchaIsCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}

Example with session string

import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const sessionString = 'identifier for a user session'
  const { checkCaptcha, componentProps } = useWHCaptcha({ configurationId, sessionString })

  ...

  const onSubmit = async () => {
    const captchaIsCorrect = await checkCaptcha()
    if (captchaIsCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}

Validation on the server

API endpoint

import { WHCaptchaApi } from '@pimred/whcaptcha'

// API route GET /api/whcaptcha
const handleRequest = async (req, res) => {
  const { solution, sessionString } = req.query
  const isCorrect = WHCaptchaApi.checkCaptcha(process.env.WHCAPTCHA_CONFIGURATION_ID, sessionString, solution)
  return res.json({ isCorrect })
}

Frontend

import { WHCaptcha, useWHCaptcha } from '@pimred/whcaptcha'
import '@pimred/whcaptcha/dist/whcaptcha.css'

const Example = () => {
  const configurationId = 'configuration from initial setup'
  const { componentProps, getSessionString, getSolution } = useWHCaptcha({ configurationId })

  ...

  const onSubmit = async () => {
    const captchaValidationFromServer = await fetch(`/api/whcaptcha?sessionString=${getSessionString()}&solution=${getSolution()}`).then(response => response.json())
    if (captchaValidationFromServer.isCorrect) {
      ...
    }
  }
  ...

  return (
    <form>
      ...
      <WHCaptcha {...componentProps} />
      <button onClick={onSubmit} />
    </form>
  )
}

API

Hook: useWHCaptcha

 const {
   checkCaptcha,
   loadCaptcha,
   getSessionString,
   getSolution,
   componentProps: {
     texts,
     images,
     clickedImages,
     handleClickOnImage,
     isSolved,
     isSubmitted,
     error
   }} = useWHCaptcha({ configurationId, sessionString })

The hook returns

• checkCaptcha: Function to perform the check of captcha
  Note: when you call checkCaptcha and the result is correct you can't call it again with the same challenge. You need to reload the captcha first (with loadCaptcha).
• loadCaptcha: Function to perform a reload of captcha
• getSessionString: Helper function to return the session string if generated by the hook
• getSolution: Helper function to return the selected solution
• componentProps: Object that should be passed to the WHCaptcha component.

<WHCaptcha {...componentProps} />

Component: WHCaptcha

Pass the props from the hook: componentProps.

• height number in pixel that will be passed to the div on order to prevent a CLS
• language language code
• className CSS class for the container
• imageClassName CSS class for every image
• headlineClassName CSS class for the headline
• bottomLineClassName CSS class for the bottomLine
• focusColor color for the captcha image when it's active