reCaptcha - Documentation (ODC)

Stable version 0.1.0 (Compatible with ODC)

Uploaded on 23 June 2023 by NTT DATA PORTUGAL, S.A

Documentation

0.1.0

How to get your Keys - Common Step:

This is a common step for all the versions of reCAPTCHA.

Create two site properties on your application to receive the Google API keys, call them vX_Key and vX_Secret. Their data type is text.
To fill in these site properties you need to sign up for an API key pair for your site. The key pair consists of a site key and a secret key. The site key is used to invoke the reCAPTCHA service. The secret key authorizes communication. Set those two key values in the two respective site properties in Service Center. Make sure to select the type of reCAPTCHA you will use in your app and repeat this step for all the types you need.

reCAPTCHA v3 - Steps to implement the reCAPTCHA v3

1. Make the component available on your application.

Install the component and manage the dependencies. Select the elements referring to the reCAPTCHA v3 below:

2. Place the component on your screen

With the Site Properties properly filled, now drag and drop the RecaptchaV3 web block to your screen, define its inputs, and start creating the logic to implement the Google reCAPTCHA v3 protection.
The recaptchaTheme, reCaptchaBadge, and HideBadge are inputs to help with the look of the Recaptcha on the screen. To help there are Static Entities provided by the component. The SiteKey input is the site property defined in the common step above.

3. Create the logic to support the reCAPTCHA v3

We need to create 3 client actions, we will call them RecaptchaV3Render, RecaptchaV3Execute, and RecaptchaV3Callback: RecaptchaV3Render: Use this action to attribute an ID to your reCAPTCHA web block, this is useful when we have more than one reCAPTCHA implementation to different elements in our screen. First, create a local variable reCAPTCHAv3_Id of type text on your screen and then create the RecaptchaV3Render client action with one input parameter called Id (type: text). Inside this action assign the local variable Id to this ID.

Define this Client Action as a Handler of the Render Event on the RecaptchaV3 web block referenced in step 2. RecaptchaV3Execute: This is the client action that should be defined as the on-click action on your button/link. This will run JavaScript (v3Execute) that will provide the data to the next action (linking it with your backend) and calculate the user 'score'. Don't create any business logic on this action.
Create a client action named RecaptchaV3Execute and create an input parameter named ActionName. Create a flow matching the following one (for the inputs asked by the v3Execute, place the local variable for the RecapchaId and the ActionName input for the Action) :

Place then this client action as the on-click Event of our Add Product and Remove Selected buttons, and define the action name as well, this input will come in handy later.

Place the V3Execute client action as the on-click event of your Button.

RecaptchaV3Callback: this callback action will run after the RecaptchaV3Execute and will determine if the business action is safe or not to be executed, based on the resulting score and the threshold defined by the developer. This result is obtained by running the v3Verify_Wrapper server action inside this client action, which will be defined now.
Create a v3Verify_Wrapper server action that will gather the response from the server, this server action should have two input parameters (In_Response (text) and In_RemoteIP(Boolean) and an output parameter of the type structure (PostSiteverifyResponse structure that comes with the component), inside the flow you should run the verify token server action that comes with the component and then assign the output of the verify token to the output of the server action. The server action flow should be similar to this:

We can now create the RecaptchaV3Callback client action. The goal of this action is to retrieve the score obtained by the interaction of the user with the website and have the logic to decide if we should let the user continue with the intended business action or block it. This is obtained by creating an if statement comparing our defining threshold with the score output that comes from the wrapper server action created just above. This score provided by the server action will be between 0.0 and 1.0. 1.0 is very likely a good interaction and 0.0 is very likely a bot.
If the verification succeeds, we need then to have a way to define what business action to execute (remember that this callback action will run when you press the add product or remove products buttons). We can define this logic by placing an if widget after the validation of the captcha and using the action name defined in the step above at the buttons on the On Click event.

Place this client action as the handler of the Callback trigger that exists on the web block that we just placed on the screen in Step 3. After concluding it will have the following configuration:

reCAPTCHA v2 CheckBox - Steps to implement the reCAPTCHA v2 Checkbox

1. Make the component available on your application.

Install the component and manage the dependencies. Select the elements referring to the reCAPTCHA v2 Checkbox below:

2. Place the component on your screen.

With the Site Properties properly filled, we can now drag and drop the RecaptchaV2 checkbox web block to our screen, define its inputs, and start creating our logic to implement the Google reCAPTCHA v2 protection.
The recaptchaTheme and reCaptchaBadge are inputs to help with the look of the recaptcha on the screen. To help there are Static Entities that are provided by the component. The SiteKey input is the site property defined in the common step.

3. Create the logic to support the reCAPTCHA v2 Checkbox.

We need to define now a couple of client actions to deal with our newly placed web block and our button to submit a form. reCaptchaCheckbox1Render: Use this action to attribute an ID to your reCAPTCHA v2 Checkbox webBlock, this is useful when we have more than one reCAPTCHA v2 Checkbox implementation on different elements in our screen. First, create a local variable Checkbox1_Id of type text on your screen and then create the reCaptchaCheckbox1Render client action with one input parameter called Id (type: text). Inside this action assign the local variable to this ID.

Define this client action as a Handler of the Render Event on the checkbox web block referred on step 2.

Your business-oriented client action: This is the action that will run when the user interacts with the screen but before running it, it will check if the checkbox was properly clicked by the user. In our use case, we are implementing a button to submit a form, so before this action occurs we need to understand if the reCaptcha v2 Checkbox was ticked. To achieve this, drag and drop the client action named GetResponse and fill the WidgetId input parameter with the created local variable Checkbox1_Id. This output will contain the response to If our checkbox was ticked or not, so we need to create an If statement to decide based on that. The client action flow for our action will look like this:

An optional callback action: You can define an action to run when the user ticks the Checkbox action. In our demo, we are just logging into our console the results of ticking the checkbox. The v2CheckboxVerify_Wrapper checks the response from the server and returns this response and the client action just displays it on the browser's console. You can implement your business action on this callback so that the action fires automatically when the user ticks the checkbox.

After defining all the actions, define the handlers of the checkbox web block with two of these created client actions, in the end, it should look like this:

reCAPTCHA v2 Invisible- Steps to implement the reCAPTCHA v2 Checkbox

1. Make the component available on your application.

Install the component and manage the dependencies. Select the elements referring to the reCAPTCHA v2 Invisible below:

2. Place the component on your screen.

With the Site Properties properly filled, now drag and drop the RecaptchaV2 Invisible web block to your screen, define its inputs, and start creating our logic to implement the Google reCAPTCHA v2 Invisible protection.
The recaptchaTheme, reCaptchaBadge, and HideBadge are inputs to help with the look of the recaptcha on the screen. To help there are Static Entities that are provided by the component.

3. Create the logic to support the reCAPTCHA v2 Invisible.

We need to define now a couple of client actions and a local variable to deal with our newly placed web block and our button to submit the form. Create a local variable of type record with the data type Record with the following configuration:

Create a client action to attribute an ID to your reCAPTCHA v2 Invisible webBlock with an input parameter named Id. This is useful when we have more than one reCAPTCHA v2 Invisible implementation on different elements in our screen. Inside this action just assign the Id attribute of the local variable to the Id input of the client action.

Create the client action to deal with the event when the user interacts with the website (in this case the button to submit the form). This action should not contain any business logic. It should trigger a client action available by the component named execute - pass the local variable Id as the widget_id of this client action. Your flow should look like this:

Create a callback client action to be executed after the Execute runs in the action defined just above. This callback is executed when the user successfully solves the captcha (meaning that either the user solved the challenge or it was not necessary). This is the action where you need to put your business logic. Place the Reset client action available by the component on the flow and link it with the Id attribute of the local variable. Your flow should look like this:

reCaptcha (ODC)

reCaptcha (ODC)