a!verifyRecaptcha( onSuccess, onError )
Allows you to verify the reCAPTCHA connection was successful and access reCAPTCHA scores to help protect your Portal against potentially malicious activity. Use the onSuccess parameter to access the score returned by reCAPTCHA with fv!score
and determine what to do based on the score result. Use the onError parameter to access any error messages with fv!error
and determine what to do if reCAPTCHA isn't working properly. The a!verifyRecaptcha()
function will only execute inside the recaptchaSaveInto parameter on a!buttonWidget()
and can only be used in Portals.
See also: reCAPTCHA Guidance
Keyword | Type | Description |
---|---|---|
|
List of Saves |
A list of saves to execute after reCAPTCHA executes successfully. Use |
|
List of Saves |
A list of saves to execute after reCAPTCHA does not execute successfully. Use |
List of Saves
The Appian Portals reCAPTCHA functionality uses Google's reCAPTCHA services and works with the a!verifyRecaptcha()
function within the recaptchaSaveInto parameter on the button component. Together, they provide a score from 0 to 1 to tell you if your Portal is likely being used by a bot or a human.
If the score is returned successfully, you can access the score in the function's onSuccess parameter using fv!score
and use it to define what happens based on whether your Portal is likely being used by a bot or a human. A score of 0.0 is very likely a bot and a score of 1.0 is very likely a human.
Because you can define the behavior based on the score you're comfortable with, you have total control over how your Portal handles bots and form submissions.
To use reCAPTCHA for your Portal, you must:
a!verifyRecaptcha()
function within the recaptchaSaveInto parameter on the button component.fv!score
in the onSuccess parameter.fv!score
in the onSuccess parameter to determine what happens based on whether a user is likely a bot or human.fv!error
in the onError parameter.Note: reCAPTCHA only works in a published portal. In an interface object, it will always evaluate the onError parameter.
See Google's unit testing for information on how to test your conditional logic and design. You can add unit testing keys to your Portal when you add your site key credentials in the reCAPTCHA connected system then republish your portal to help you test out your expressions and logic.
For examples of conditional logic using the a!verifyRecaptcha()
function within the recaptchaSaveInto parameter on the button component, see the Submit button with a!verifyRecaptcha() example below.
For more information on reCAPTCHA, check out our reCAPTCHA guidance.
The a!verifyRecaptcha()
function has two parameters: onSuccess and onError. Write expressions for both parameters to determine what will happen if reCAPTCHA connects successfully (onSuccess) or if there is an error with reCAPTCHA (onError).
For the onSuccess parameter, define logic that determines what will happen when a!verifyRecaptcha
successfully connects to reCAPTCHA and reCAPTCHA returns a score, accessed using fv!score
.
For example, you could define logic so that if the score is 0 to 0.5, the form cannot be submitted. Or you could define your logic so that if the score is below 0.7, the form is submitted but flagged for review.
Note: Appian uses the first score returned by reCAPTCHA for all instances of the a!verifyRecaptcha()
function's onSuccess parameter within an interface, regardless of the number of user interactions in the page.
For the onError parameter, define logic that determines what will happen when there is an error with the reCAPTCHA service, such as a connection error or incorrect keys. To access the error, use fv!error
.
For example, you may want to save the error message so that you can view it later or define a custom set of error messages to show to the user.
1
2
3
4
onError: {
a!save(local!displayErrorMessage, true),
a!save(local!errorMessageDetails, fv!error)
}
The following example shows only the a!verifyRecaptcha()
function. When you use it in a Portal, you must put this expression inside the recaptchaSaveInto parameter of a submit button on an interface. If you copy and paste the example into an expression editor, reCAPTCHA will not work. Use this example only as a reference.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
a!verifyRecaptcha(
onSuccess: {
if(
fv!score > .7,
{
a!save(local!submissionDetails.needsReview, false),
a!writeToDataStoreEntity(
dataStoreEntity: cons!PORTAL_ENTITY,
valueToStore: local!submissionDetails,
onSuccess: {
a!save(local!submissionStatus, "SUCCESS"),
a!save(local!confirmationMessage, "Your submission is confirmed.")
}
)
},
if(
fv!score > .3,
{
a!save(local!submissionDetails.needsReview, true),
a!writeToDataStoreEntity(
dataStoreEntity: cons!PORTAL_ENTITY,
valueToStore: local!submissionDetails,
onSuccess: {
a!save(local!submissionStatus, "WARN"),
a!save(local!confirmationMessage, "Your submission is processing. You will receive an email shortly with confirmation details. If you do not hear from us soon, please try again or give us a call.")
}
)
},
{
a!save(local!submissionStatus, "ERROR"),
a!save(local!confirmationMessage, "Your submission could not be confirmed. Please try again or contact us.")
}
)
)
},
onError: {
a!save(local!submissionStatus, "ERROR"),
a!save(local!confirmationMessage, "Your submission could not be confirmed. Please try again or contact us.")
}
)
Feature | Compatibility | Note |
---|---|---|
Portals | Compatible | |
Offline Mobile | Incompatible | |
Sync-Time Custom Record Fields | Incompatible | |
Real-Time Custom Record Fields | Incompatible | Custom record fields that evaluate in real time must be configured using one or more Custom Field functions. |
Process Reports | Incompatible | Cannot be used to configure a process report. |
Process Events | Incompatible | Cannot be used to configure a process event node, such as a start event or timer event. |
a!verifyRecaptcha