Description

With this JavaScript library you can connect to a kzCaptcha installation and verify the submitted data.

Installation

Install this library by using npm:

npm install @kuantaz/api-client

Usage

1. Create a project in your kzCaptcha installation
2. Include the kzCaptcha script in your form

<div id="kzCaptcha-box"></div>

<script src="https://[URL]/build/kzCaptcha-frontend.js" defer></script>
<script>
  var m;
  window.onload = function () {
    m = new kzCaptcha("kzCaptcha-box", "https://[URL]", "[UUID]", "[PUBLIC_KEY]", { loadCssResource: true });
  };
</script>

3. Include the library in your project

const kzCaptcha = require('@kzCaptcha/api-client');

4. After the form was submitted, verify the data before processing it

let client = new kzCaptcha.Client(host, publicKey, privateKey, {});

kzCaptchaSubmitToken = formData._kzCaptcha_submitToken;
kzCaptchaValidationToken = formData._kzCaptcha_validationToken;

client.verifySubmission(formData, kzCaptchaSubmitToken, kzCaptchaValidationToken).then((verificationResult) => {
  if (verificationResult.isSubmittable()) {
    // Send the email or process the data
  } else {
    // Show error message
  }
});

API Documentation

Client

Client initialization

Create a new client object to use the API client.

/**
 * @param string url URL of the kzCaptcha installation
 * @param string publicKey Public key of the kzCaptcha project
 * @param string privateKey Private key of the kzCaptcha project
 * @param array args Arguments for the axios request
 */
let client = new Client(url, publicKey, privateKey, args);

Verify form data

To verify the form data, call verifySubmission with the form data in an array and the submit and validation token, which kzCaptcha generated on the form initialization and the form data validation. The method will return a new Promise object that is resolved with the VerificationResult object.

/**
 * @param array formData Array with the form values. All not-processed fields by kzCaptcha (hidden, checkbox,
 *                       radio and so on) have to be removed from this array
 * @param string kzCaptchaSubmitToken Submit token which kzCaptcha returned on the form initialization
 * @param string kzCaptchaValidationToken Validation token which kzCaptcha returned after the form was validated
 * @return Promise Returns a Promise object that is resolved with a VerificationResult object
 */
client.verifySubmission(formData, kzCaptchaSubmitToken, kzCaptchaValidationToken).then((validationResult) => {
  if (verificationResult.isSubmittable()) {
    // Do your stuff, e.g. sending emails...
  }
});

VerificationResult

Constants

- FIELD_NOT_VERIFIED: 'not-verified'
- FIELD_VALID: 'valid'
- FIELD_INVALID: 'invalid'

isSubmittable(): boolean

Returns true, if the form is submittable. This means that the verification was successful and the form data are valid.

isValid(): boolean

Returns true, if kzCaptcha determined the form as valid. The difference to isSubmittable() is, that this is the raw result from kzCaptcha while isSubmittable() also checks if the verification was done correctly.

getVerifiedFields(): array (see Constants)

Returns an array with all verified field keys.

getVerifiedField(key): string (see Constants)

Returns the verification status of one field.

hasIssues(): boolean

Returns true, if there were verification issues.

getIssues(): array

Returns an array with all verification issues.