Skip to content

Commit f2c3a3a

Browse files
greenbergagreenberga
authored
Merge pull request #61 from FriendlyCaptcha/salesforce-integration
Add documentation for Salesforce integration
2 parents b7cd10d + fd7905f commit f2c3a3a

18 files changed

+1144
-0
lines changed

‎src/integrations.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,15 @@ export const INTEGRATIONS: Integration[] = [
9797
link: "https://github.com/studiomitte/friendlycaptcha-typo3",
9898
github: "studiomitte/friendlycaptcha-typo3",
9999
},
100+
{
101+
name: "Salesforce",
102+
slug: "salesforce",
103+
tags: ["CMS"],
104+
fcVersion: "v2",
105+
image: "salesforce.svg",
106+
link: "/integrations/salesforce/",
107+
github: "FriendlyCaptcha/friendly-captcha-salesforce",
108+
},
100109

101110
// Libraries and SDKs
102111
{

‎src/pages/integrations/salesforce/index.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
---
2+
title: Salesforce Integration
3+
description: Integrate Friendly Captcha into your Salesforce environment
4+
---
5+
6+
<img width="100" src="/img/integrations/salesforce.svg" alt="Salesforce logo" />
7+
8+
# Friendly Captcha for Salesforce
9+
10+
<!-- To integrate Friendly Captcha into your Salesforce environment, you can use [Friendly Captcha for Salesforce][appexchange], a package available on Salesforce AppExchange. -->
11+
12+
Integrating Friendly Captcha involves a front-end component and a back-end component. We recommend familiarizing yourself with the [Friendly Captcha documentation][fcdocs] to develop a baseline understanding of how an integration works.
13+
14+
For the front-end component of the integration, this package provides a Lightning Web
15+
Component (LWC). If you're using Visualforce, you should be able to insert
16+
[the standard markup][html] for the front-end integration, instead of using the LWC.
17+
18+
For the back-end component of the integration, this package provides an Apex class that
19+
performs an HTTP request to the Friendly Captcha site verification API.
20+
21+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
22+
<img src="/img/salesforce-architecture.png" alt="Architecture diagram of Friendly Captcha for Salesforce" />
23+
<figcaption><i>Architecture diagram of Friendly Captcha for Salesforce</i></figcaption>
24+
</figure>
25+
26+
The LWC or HTML scripts render a Friendly Captcha widget on your website. After the challenge is solved, the solution is passed to your back-end, where the Apex class is used to verify the solution in a request to the Friendly Captcha API. Both the LWC and the Apex class can read configuration settings from a Custom Metadata Type Record.
27+
28+
## Configuration
29+
30+
To use Friendly Captcha for Salesforce, there are a few configuration parameters that you have to supply. At minimum, you have to supply a [sitekey][sitekey-instructions] for the front-end integration and an [API key][apikey-instructions] for the back-end integration.
31+
32+
There are a few different ways to configure your integration with the required values.
33+
34+
### Custom Metadata Type Record
35+
36+
A simple way to set the configuration parameters is to add them to the Custom Metadata Type Record. Both the LWC and the Apex class will by default read the parameters from this record.
37+
38+
Navigate to Setup, search for "Custom Metadata Types", and click through to visit the page. From the list of CMDTs, find the one with the API Name **friendlycaptcha__Config__mdt**.
39+
40+
<figure style={{ textAlign: 'center', margin: '3em auto', maxWidth: 720 }}>
41+
<img src="/img/salesforce-cmdt.png" alt="Custom Metadata Types in Salesforce" />
42+
<figcaption><i>Custom Metadata Types in Salesforce</i></figcaption>
43+
</figure>
44+
45+
Click the **Manage Records** link, and then edit the **Settings** record. You'll see a form where you can set values for the various configuration parameters available.
46+
47+
<figure style={{ textAlign: 'center', margin: '3em auto', maxWidth: 720 }}>
48+
<img src="/img/salesforce-settings.png" alt="Configuration settings in Salesforce" />
49+
<figcaption><i>Configuration settings in Salesforce</i></figcaption>
50+
</figure>
51+
52+
**Verification Settings** are used by the back-end (Apex class). **Widget Settings** are used by the LWC. **Shared Settings** are used by both. Make sure you enter at least a sitekey and an API key. The following table provides a summary of the configuration options.
53+
54+
| Setting | Location | Description |
55+
| -- | -- | -- |
56+
| Sitekey | Shared | A Friendly Captcha sitekey associated with an application. You can find this value in the application configuration in the Friendly Captcha dashboard. |
57+
| APIEndpoint | Shared | The endpoint URL used for communicating with the Friendly Captcha API. Shorthands &apos;eu&apos; or &apos;global&apos; are accepted. Default is &apos;global&apos;. Using the &apos;eu&apos; endpoint requires access that must be enabled in the Friendly Captcha dashboard. |
58+
| APIKey | Apex | An API key used for communicating with the Friendly Captcha API. You can create an API key in the Friendly Captcha dashboard. |
59+
| Strict | Apex | Determines the failure mode behavior of the captcha response verification (siteverify) result. This mode only applies when the API was not able to verify the response, which might occur for network connectivity reasons or a misconfiguration of the client. When &apos;strict&apos; is enabled, unverified responses will be set to &apos;reject&apos; (i.e. fail-closed behavior). When disabled (the default), unverified responses will be set to &apos;accept&apos; (i.e. fail-open behavior). |
60+
| Timeout | Apex | How long (in milliseconds) to wait for a captcha response verification request to complete. |
61+
| StartMode | LWC | The start mode determines the behavior around automatic activation of the widget. Activation here means the challenge gets requested and gets solved. |
62+
| Theme | LWC | The theme for the widget. |
63+
| Language | LWC | Language code such as "en" for English or "de" for German. Defaults to automatic language detection. Usually you should not set this yourself and instead let the widget detect the language automatically. |
64+
65+
### Apex Class
66+
67+
You can directly set back-end configuration parameters using the `friendlycaptcha.Options` Apex class. Here's what that looks like:
68+
69+
```
70+
friendlycaptcha.Options opts = new friendlycaptcha.Options()
71+
.apiKey('<API KEY>')
72+
.sitekey('<SITEKEY>')
73+
.apiEndpoint('<API ENDPOINT>')
74+
.strict(<true/false>)
75+
.timeout(<int>);
76+
```
77+
78+
You then pass the `friendlycaptcha.Options` instance to the `verifyCaptchaResponse` method.
79+
80+
```
81+
friendlycaptcha.VerifyResult result = friendlycaptcha.Client.verifyCaptchaResponse('<CAPTCHA RESPONSE>', opts);
82+
```
83+
84+
### Lightning Web Component
85+
86+
You can pass front-end configuration parameters to the `<friendlycaptcha-widget>` LWC like this:
87+
88+
```
89+
<friendlycaptcha-widget
90+
sitekey="SITEKEY"
91+
apiEndpoint="API ENDPOINT"
92+
startMode="STARTMODE"
93+
language="LANGUAGE"
94+
theme="THEME"
95+
></friendlycaptcha-widget>
96+
```
97+
98+
## Flow Example
99+
100+
This example shows how to use Friendly Captcha for Salesforce in a Flow. We'll create a simple login screen that displays a Friendly Captcha Widget and includes server-side captcha verification. The pattern outlined here should be translatable anywhere you can use LWCs and Apex classes.
101+
102+
### Create a new Screen Flow in Setup
103+
104+
This will open the Flow Builder app with Start and End elements. Add a Screen Flow with an Email component and a Password component, and then scroll down to the list of custom components to add a Friendly Captcha Widget component. If you haven't configured your integration by following [the steps listed above](#configuration), make sure to at least add a value for the Sitekey field at this step (under **Properties**).
105+
106+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
107+
<img src="/img/salesforce-screen-flow.png" alt="Configuring a Screen Flow" />
108+
<figcaption><i>Configuring a Screen Flow</i></figcaption>
109+
</figure>
110+
111+
### Create an Apex Action to verify the captcha response
112+
113+
Navigate to Apex Classes in Setup. Create a new Apex Class with the following content.
114+
115+
```
116+
public class LoginAction {
117+
118+
@InvocableMethod(label='Verify Captcha')
119+
public static List<Response> verify(List<Request> requests) {
120+
List<Response> responses = new List<Response>();
121+
122+
for (Request request : requests) {
123+
Response response = new Response();
124+
friendlycaptcha.VerifyResult result = friendlycaptcha.Client.verifyCaptchaResponse(request.captchaResponse);
125+
response.success = result.shouldAccept();
126+
if (result.getErrorDetail() != null) {
127+
response.error += result.getErrorDetail();
128+
}
129+
responses.add(response);
130+
}
131+
132+
return responses;
133+
}
134+
135+
public class Request {
136+
@InvocableVariable(label='Captcha Response' required=true)
137+
public String captchaResponse;
138+
139+
@InvocableVariable(label='Sitekey' required=false)
140+
public String sitekey;
141+
}
142+
143+
public class Response {
144+
@InvocableVariable(label='Error')
145+
public String error = '';
146+
147+
@InvocableVariable(label='Success')
148+
public Boolean success;
149+
}
150+
}
151+
```
152+
153+
This Apex Action calls the Friendly Captcha API to verify the captcha response generated in the previous Flow element. If Friendly Captcha is able to verify the captcha response, the `success` flag is set to true. Any errors returned by the API are also included in the output of this Flow element.
154+
155+
The `friendlycaptcha.Client.verifyCaptchaResponse()` method requires an API key for authentication. Make sure you've configured an API key as outlined in the documentation on [configuration](#configuration).
156+
157+
You could perform other kinds of validation (for example on the email and password) in this action as well. Save the Apex class and return to your Screen Flow.
158+
159+
### Add the "Verify Captcha" Apex Action to your Screen Flow
160+
161+
It should come after the Login Screen element. Make sure to connect the "Captcha Response" (and optionally "Sitekey") variables from the Screen element as inputs to the Apex Action element.
162+
163+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
164+
<img src="/img/salesforce-apex-action.png" alt="Configuring an Apex Action" />
165+
<figcaption><i>Configuring an Apex Action</i></figcaption>
166+
</figure>
167+
168+
### Add a Decision element based on the output of the Apex Action
169+
170+
You can use the `success` and `error` output variables of the Apex Action to render success or failure screens. Add a Decision element that leads to "Success" or "Failure" based on whether the `success` variable is true or false. In this example, depending on whether the verification is successful, a different screen is presented.
171+
172+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
173+
<img src="/img/salesforce-flow-decision.png" alt="Configuration of a Decision Flow element" />
174+
<figcaption><i>Configuration of a Decision Flow element</i></figcaption>
175+
</figure>
176+
177+
In this implementation, we chose to render Screen elements that showed a simple confirmation text on success, and a failure message otherwise. In the failure message, you can conditionally render the error message if it's present:
178+
179+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
180+
<img src="/img/salesforce-flow-error.png" alt="Conditionally display an error message" />
181+
<figcaption><i>Conditionally display an error message</i></figcaption>
182+
</figure>
183+
184+
Here's the final Flow:
185+
186+
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
187+
<img src="/img/salesforce-flow-final.png" alt="Complete Salesforce Flow example" />
188+
<figcaption><i>Complete Salesforce Flow example</i></figcaption>
189+
</figure>
190+
191+
## API Reference
192+
193+
### Apex Class
194+
195+
[Click here for the Apex reference documentation.](reference/)
196+
197+
### Lightning Web Component
198+
199+
Using the LWC from code (e.g. from within another LWC) looks like this:
200+
201+
```
202+
<friendlycaptcha-widget
203+
sitekey={sitekey}
204+
api-endpoint={endpoint}
205+
theme={theme}
206+
start-mode={startMode}
207+
language={language}
208+
></friendlycaptcha-widget>
209+
```
210+
211+
Note that all properties (except `sitekey`) are optional and have sensible defaults. The LWC will attempt to read these properties from the "Settings" record of the `Config__mdt` CMDT; properties passed directly to the LWC take precedence.
212+
213+
The LWC also exposes all events exposed by [the widget itself][widget-events]:
214+
215+
```
216+
<friendlycaptcha-widget
217+
sitekey={sitekey}
218+
oncomplete={handleComplete}
219+
onerror={handleError}
220+
onexpire={handleExpire}
221+
onstatechange={handleStateChange}
222+
></friendlycaptcha-widget>
223+
```
224+
225+
Each event handler receives an `event` argument with a `detail` property matching the shapes documented on the [Widget SDK Events page][widget-events].
226+
227+
[appexchange]: #
228+
[fc]: https://friendlycaptcha.com
229+
[fcdocs]: https://developer.friendlycaptcha.com/docs/v2/getting-started
230+
[html]: https://developer.friendlycaptcha.com/docs/v2/getting-started/install#option-a-html-scripts
231+
[sitekey-instructions]: /docs/v2/getting-started/setup
232+
[apikey-instructions]: /docs/v2/api/authentication#creating-api-keys
233+
[widget-events]: /docs/v2/sdk/events

‎src/pages/integrations/salesforce/reference/classes/Client.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Client Class
2+
3+
Client is the class that offers functions for validating Friendly Captcha
4+
responses generated by the Friendly Captcha widget.
5+
6+
## Methods
7+
### `verifyCaptchaResponse(response, opts)`
8+
9+
#### Signature
10+
```apex
11+
global static VerifyResult verifyCaptchaResponse(String response, Options opts)
12+
```
13+
14+
#### Parameters
15+
| Name | Type | Description |
16+
|------|------|-------------|
17+
| response | String | |
18+
| opts | [Options](Options) | |
19+
20+
#### Return Type
21+
**[VerifyResult](VerifyResult)**
22+
23+
---
24+
25+
### `verifyCaptchaResponse(response)`
26+
27+
Reads configuration options from the &#x27;Settings&#x27; record of the
28+
[Config__mdt](../custom-objects/Config__mdt) .
29+
30+
#### Signature
31+
```apex
32+
global static VerifyResult verifyCaptchaResponse(String response)
33+
```
34+
35+
#### Parameters
36+
| Name | Type | Description |
37+
|------|------|-------------|
38+
| response | String | |
39+
40+
#### Return Type
41+
**[VerifyResult](VerifyResult)**

0 commit comments

Comments
 (0)