CorvidReference

wix-captcha-backend

Note: This feature is not yet available to all users.

The wix-captcha-backend module contains functionality for working with the reCAPTCHA element from backend code.

The reCAPTCHA element allows you to present a challenge-response test to site visitors to determine whether they are human or a bot. Use the reCAPTCHA element to verify that site visitors are human before allowing them perform restricted operations.

For more information on working with your reCAPTCHA element, click here.

To use the Captcha API, import wixCaptcha from the wix-captcha-backend module:

   import wixCaptcha from 'wix-captcha-backend';

Table of Contents

FUNCTIONS

?
Perform actions on an object.
authorize( )Authorizes the reCAPTCHA token.

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
ErrorReportAn object representing a reCAPTCHA authorization error message.
SuccessReportAn object representing a reCAPTCHA authorization success message.

authorize( )

Authorizes the reCAPTCHA token.

Description

Following reCAPTCHA verification on the client side, you must authorize the generated reCAPTCHA token in the backend. authorize() checks if the token is valid, making sure it was not tampered with or timed out.

The authorize() function returns a Promise that resolves to a Success object when the token is authorized and to an Error object when authorization fails.

To understand how authorize() is used in a typical reCAPTCHA validation lifecycle, click here.

See Also

Captcha( )

Syntax

function authorize(token: string): Promise<SuccessReport>
PARAMETERS
?
Values that you pass to a function.
token
string
The reCAPTCHA token to authorize.
RETURN VALUE
?
Value that a function evaluates to when it is finished running.
Promise<SuccessReport>

Fulfilled - A success message. Rejected - An error message.

Examples

Full reCAPTCHA lifecycle scenario

This example demonstrates how to use reCAPTCHA to protect a data insertion. We use a text input for the data, a reCAPTCHA element, and a submit button. The submit button is disabled until the site visitor completes the reCAPTCHA challenge and the reCAPTCHA is verified. Clicking the submit button triggers backend authorization of the token. If authorization is successful, the data is inserted into the collection.

/************************************
 * backend code - submitHandler.jsw *
 ************************************/

import wixCaptcha from 'wix-captcha-backend';
import wixData from 'wix-data';

// Authorize token and insert data
export function processSubmission(submitRequestData) {
  return wixCaptcha.authorize(submitRequestData.token)
    .then (() => {
      return wixData.insert("MyCollection", submitRequestData.data);
    });
}

/********************
 * client-side code *
 ********************/

import {processSubmission} from 'backend/submitHandler';

$w.onReady(function () {
  // When user clicks submit button
  $w("#submitDataButton").onClick(() =>
    let submitRequestData = {
      token: $w("#myCaptcha").token,
      data: $w("#myInput").value,
    }
    processSubmission(submitRequestData) // Call backend function
      .then( () => {
        $w("#myCaptcha").reset();
        $w("#submitDataButton").disable();
        $w("#messageText").text = "Data successfully submitted";
        $w("#messageText").show();
      })
      .catch( () => {
        $w("#myCaptcha").reset();
        $w("#submitDataButton").disable();
        $w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
        $w("#messageText").show();
      })
  }

  // Error handler
  $w("#myCaptcha").onError(() => {
    $w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
    $w("#messageText").show();
  })

  // Verification handler
  $w("#myCaptcha").onVerified(() => {
    $w("#submitDataButton").enable();
    $w("#messageText").hide();
  })

  // Timeout handler
  $w("#myCaptcha").onTimeout(() => {
    $w("#submitDataButton").disable();
  })
});

ErrorReport

An object representing a reCAPTCHA authorization error message.

Description

If reCAPTCHA token authorization fails, an error message containing a status code is returned. The following table lists the possible HTTP error status codes, based on RFC 2616:

Status CodeNameDescription
400Bad RequestThe request could not be understood by the server. This could occur for a number of reasons, such as:

  • The request was sent without a token.
  • The token is invalid.
  • The token has timed out.
401UnauthenticatedNo user identity found in passed request.
500Internal Server ErrorThe server encountered an unexpected condition, such as a missing or invalid private reCAPTCHA key.
503UnavailableThe service is unavailable due to one of the following:

  • Throttled error: Server overload due to more than the allowed requests in a given time frame.
  • Request failed: No response following 10 retries with a 1-second interval.

See Also

authorize( )

Syntax

type ErrorReport = {
  error: string
}
MEMBERS
?
The properties of an object.
error
string
Error message.

Examples

Authorization fails and returns an error

/************************************
 * backend code - submitHandler.jsw *
 ************************************/

import wixCaptcha from 'wix-captcha-backend';

export function captchaAuthorize(token) {
  return wixCaptcha.authorize(token);
}

/********************
 * client-side code *
 ********************/

import {captchaAuthorize} from 'backend/submitHandler';

export function myButton_click(event, $w) {
  let myToken = $w("#myCaptcha").token;

  captchaAuthorize(myToken)
    .then( (result) => {
      console.log (result);
    })
    .catch((error) => {
      console.log (error); // Request failed with status code 400
      $w("#myCaptcha").reset();
      $w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
      $w("#messageText").show();
    })
}

SuccessReport

An object representing a reCAPTCHA authorization success message.

See Also

authorize( )

Syntax

type SuccessReport = {
  success: boolean
}
MEMBERS
?
The properties of an object.
success
boolean
Value is true when authorization is successful.

Examples

Authorize reCAPTCHA token and show result

/************************************
 * backend code - submitHandler.jsw *
 ************************************/

import wixCaptcha from 'wix-captcha-backend';

export function captchaAuthorize(token) {
  return wixCaptcha.authorize(token);
}

/********************
 * client-side code *
 ********************/

import {captchaAuthorize} from 'backend/submitHandler';

export function myButton_click(event, $w) {
  let myToken = $w("#myCaptcha").token

  captchaAuthorize(myToken)
    .then( (result) => {
      console.log (result); // {success: true}
    })
    .catch(() => {
      $w("#myCaptcha").reset();
      $w("#messageText").text = "Something went wrong. Redo the reCAPTCHA challenge.";
      $w("#messageText").show();
    })
}