Google reCaptcha v1.1

This package provides capabilities that extend the Avoka Transact platform for customers wishing to protect their applications from spam and abuse in their forms using the Google reCaptcha services. Google reCaptcha is a free service that uses advanced risk analysis techniques to tell humans and bots apart.

The package supports 2 different experiences to perform the reCaptcha validation.

  1. Visible reCaptcha v2 - Upon choosing this option, the applicant will be aware of the validation and will trigger it by clicking the "I'm not a robot" check box.
  2. Invisible reCaptcha - Upon choosing this option, the applicant will not be able to know when the validation takes places. It will be up to the form builder to decide when to trigger the validation.

The level of security for each validation is available under security preference in Google reCaptcha admin view.

Google reCaptcha supports the following languages:

To support this functionality this package includes the following:

  1. Google reCaptcha component

    This maestro native component can be used by form developers by adding it into the form structure where the reCaptcha UI will be displayed.

    NOTE: that even the invisible reCaptcha type needs to have a placeholder in the form where potential notification messages or additional captcha checks requiring user actions will be displayed.

  2. Dynamic data service (DDS): Google reCaptcha - verify

    This DDS is called immediately as the client side reCaptcha verification token has been obtained from Google. To complete the verification process the token must be passed on the Transact server and verified by the Google backend API. The DDS uses the clients secret key and the token to do so. The result of the backend verification is then passed back into the web client in the same DDS call response.

Process Flow

The bellow diagram displays the sequence of events which occur at run time when using the google reCaptcha verification:

  1. Form is loaded in the web browser
  2. The user navigates to the page X - reCaptcha widget is rendered
  3. The user is "recognized"
    1. reCaptcha v2 - by clicking the "I am not a robot" checkbox
    2. Invisible - the recognition is triggered immediately when the widget is rendered (user navigated to the page/section where the reCpatcha widget is placed)
    The widget requests a new recaptcha token from the Google API
  4. When Google provisions a new token (also referred to as recaptcha response) the built in tokenCallback JS methods is called and the token is passed on it
  5. The token is immediately verified on the TM server
    1. tokenCallback calls the Google reCaptcha - Verify TM DDS
    2. The Google reCaptcha - Verify DDS requests the Google API to verify the token by providing the client's google reCaptcha secret key
    3. if Google responds with a successful verification result the DDS sets the "google.recaptcha.verified=true" submission property on the current Transaction
    4. the verification result is returned back into the form
  6. based on the server verification result one of the form's onSuccess or onFailure rules is executed
  7. The from developer can utilize and implement any of the listed TM services to perform a later server side check that the current Txn has been successfully reCaptcha verified be fetching the Txn "google.recaptcha.verified " submission property set to "true"
    Submission Data Validator
    Saved Processor
    Dynamic Data Service
    Submission Complete Processor


Any client who wishes to use the proposed Avoka Exchange reCaptcha component will need to use their own Google account and sign up for their own key pair as per the usual process described at Note that Google requires individual registration for different reCatpcha types. While the same google account can be used for multiple registrations, each will use a different set of site&secret keys to be configured on the web application (Avoka form).

More on obtaining Keys:


This package has the following compatibility requirements:

Transact Manager5.0 or above
Transact Maestro5.0.0 or above

CSP Configuration

The Content Security Policy (CSP) response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via a HTTP Header, thereby protecting your solution from a range of vulnerability attacks.

By default, Avoka Transact has strict CSP settings configured so these will likely need to be modified in order to enable the Google reCaptcha JavaScript API integration.

You can configure CSP settings in Transact Manager at a system wide level via the 'Form Submission Access Controller' service, or at an Organization level in the Security tab.

In order to load the externally hosted google javascript assets on the forms the Security CSP Header needs to be updated to enable loading web page assets from the following two domains:

The following Sample CSP demonstrates how to enable the Google reCaptcha integration:

script-src 'self'; object-src 'none'

For more information see CSP on The Avoka Community

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.

    Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.

  5. Import each archive found in the libraries folder to Maestro.

    Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Usage Instructions

Use the following procedure to configure Google reCaptcha component in your form:

  • Add the Google reCaptcha component onto your page.
  • In the Configuration section:
    • Select the reCaptcha type: reCaptcha v2 or Invisible reCaptcha.
    • Set the site key. (You should have Google site key specific to the reCaptcha type you selected before)
    • Select the reCaptcha theme.
    • Select the language key or leave it on default 'en'
    • if the reCaptcha type is Invisible, you can thick the option Execute on widget init (Invisible only) to make the reCaptcha call on rendering the page, otherwise manually call the JavaScript method when required grecaptcha.execute();
    • Change the progress message if required or remove it completely. It is recommended to remove the progress message when you use the Invisible ReCaptcha type.
  • In the Rules section, add any processing rules to handle On Success, On Failure events.
  • Verify you setup the Google reCaptcha service connection according to the instruction below.

NOTE: In order to bypass the recaptcha checks for functional tests, you can use Google's static test api keys pair. These can be find here.

Using the component in Transact applications

On top of the configuration described above the form developers can prevent enforcing the user to go through the reCaptcha verification by implementing a visibility rule on the widget. If the widget is hidden the verification is not enforced (required) nor executed. For example it might be desired that the reCaptcha verification is not required in subsequent form sessions upon a resume of a saved form when the user has already been verified in one of the previous form sessions. This would be a very standard scenario as its expected that saved anonymous forms are resumed after the user enters a save challenge question answer which would prevent any bots from accessing such transactions. It would be recommended not using the reCaptcha in other means of user authenticated sessions either.

The widget is implemented as "bindable" which means its value can be bound to a XML element in the submission payload. The value of the widget is the result of the verification processes. The value can be undefined/true/false.

undefined - the verification hasnt been executed yet

false - the last verification failed

true - the last verification was successfull

If the the recaptcha verification is required in every form session (fresh or resumed transactions) the form developer can keep the widget always dispalyed in the form however must ensure the "google.recaptcha.verified" submission property is reset (nullified) when resuming the saved form in the Form prefill or Form security filter services.

Release Notes

Version 1.1 May 14, 2019

  • Enhanced to configure the site key without a need to re-build the applications when progressing to more advanced environments (test,stage,prod).
  • Note: Keep your site key before upgrading the Maestro library, after the upgrade, the site key must be set in service connections.

Version 1.0 Jul 20, 2018

  • Baseline release.

Maestro Assets

Google reCaptcha Library: Category: Google reCaptcha

Google reCaptcha component

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

  • On Success :

    A form developer will be able to configure the onSuccess rule which will be auto-triggerred when the user has been successfully verified (server side included). The rule will provide a great placeholder for custom logic like:

    • enable navigation through the form upon successful reCatpcha verification only
    • make form blocks visible
    • display notification messages about the verification process
  • On Failure :

    A form developer will be able to configure the onFailure rule which will be auto-triggerred when the verification process failed. The rule will provide a great placeholder for custom logic like:

    • display notification messages about the verification process failure advising the user to try again/later
    • make form blocks visible

Rule Helpers

The following rule helpers can be used when right-clicking on this component in a script editor:

  • Execute Recaptcha


Property Category Description Type Default
Google reCaptcha Type Configuration

Mandatory drop down with the below options.
For more information go to:


  • reCaptcha : reCaptcha V2
  • inVisibleReCaptcha : Invisible reCaptcha
Language Configuration

Optional text field - forces the widget to render in a specific language.
For more information go to:

text en
Theme Configuration

Google reCaptcha Theme.
For more information go to:


  • light : Light
  • dark : Dark
option light
Execute on widget init (Invisible only) Configuration

This option is for Invisible reCaptcha only. When checked, reCaptcha will be triggered on widget init.

boolean false
Message Progress Message

Google reCaptcha verify progress message

text Verifying ...


Google reCaptcha - Verify v1
Google reCaptcha Verify Service is used for verifying the response reCaptcha token by the Google backend API. For information on how inputs affect returned results see Verifying the user's response

Service Connection


Module Compatibility
Manager 5.0


Name Description Required
fetchSiteKey When the fetchSiteKey flag is set the service returns the Google site key. Yes
gRecaptchaResponse reCAPTCHA response token Yes


Name Description
isVerified When there is a verification result from Google reCaptcha API. (true | false)
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.

errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.

Service Connections

The following service connections are used by this package.

Google reCaptcha
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Must point to Google reCaptcha API at: Yes
Auth Key Must contain reCAPTCHA the secret key. Yes
Username Must contain the reCAPTCHA site key. Yes