Skip to content

Commit 04bd9d9

Browse files
greenbergagreenberga
committed
Add API reference documentation
1 parent 7c53ff6 commit 04bd9d9

9 files changed

Lines changed: 925 additions & 24 deletions

File tree

‎src/integrations.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,8 +103,8 @@ export const INTEGRATIONS: Integration[] = [
103103
tags: ["CMS"],
104104
fcVersion: "v2",
105105
image: "salesforce.svg",
106-
link: "/integrations/salesforce",
107-
github: "#",
106+
link: "/integrations/salesforce/",
107+
github: "FriendlyCaptcha/friendly-captcha-salesforce",
108108
},
109109

110110
// Libraries and SDKs

src/pages/integrations/salesforce.md renamed to src/pages/integrations/salesforce/index.md

Lines changed: 53 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: Integrate Friendly Captcha into your Salesforce environment
77

88
# Friendly Captcha for Salesforce
99

10-
To integrate Friendly Captcha into your Salesforce environment, you can use [Friendly Captcha for Salesforce][appexchange], a package available on Salesforce AppExchange.
10+
<!-- To integrate Friendly Captcha into your Salesforce environment, you can use [Friendly Captcha for Salesforce][appexchange], a package available on Salesforce AppExchange. -->
1111

1212
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.
1313

@@ -83,7 +83,7 @@ friendlycaptcha.VerifyResult result = friendlycaptcha.Client.verifyCaptchaRespon
8383

8484
### Lightning Web Component
8585

86-
You can pass front-end configuration parameters to the `<friendlycaptcha-widget>` LWC as follows.
86+
You can pass front-end configuration parameters to the `<friendlycaptcha-widget>` LWC like this:
8787

8888
```
8989
<friendlycaptcha-widget
@@ -97,17 +97,11 @@ You can pass front-end configuration parameters to the `<friendlycaptcha-widget>
9797

9898
## Flow Example
9999

100-
This example shows how to use Friendly Captcha for Salesforce in a Flow. We'll create
101-
a simple login screen that displays a Friendly Captcha Widget and includes server-side
102-
captcha verification.
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.
103101

104102
### Create a new Screen Flow in Setup
105103

106-
This will open the Flow Builder app with Start and End elements. Add a Screen Flow with
107-
an Email component and a Password component, and then scroll down to the list of custom
108-
components to add a Friendly Captcha Widget component. If you haven't configured your
109-
integration by following the steps listed above, make sure to at least add a value for
110-
the Sitekey field at this step.
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**).
111105

112106
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
113107
<img src="/img/salesforce-screen-flow.png" alt="Configuring a Screen Flow" />
@@ -156,19 +150,15 @@ public class LoginAction {
156150
}
157151
```
158152

159-
This Apex Action performs a Friendly Captcha API call to verify the captcha response from the previous element in the
160-
Flow. If Friendly Captcha is able to verify the captcha response, the `success` flag is set to true. Any errors
161-
returned by the API are also included in the output of this Flow element.
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.
162154

163155
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).
164156

165-
You could perform other kinds of validation (for example on the email and password) in this action as well.
166-
Save the Apex class and return to your Screen Flow.
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.
167158

168159
### Add the "Verify Captcha" Apex Action to your Screen Flow
169160

170-
It should come after the Login Screen element. Make sure to connect the "Captcha Response" (and optionally "Sitekey")
171-
variables from the Screen element as inputs to the Apex Action element.
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.
172162

173163
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
174164
<img src="/img/salesforce-apex-action.png" alt="Configuring an Apex Action" />
@@ -177,26 +167,67 @@ variables from the Screen element as inputs to the Apex Action element.
177167

178168
### Add a Decision element based on the output of the Apex Action
179169

180-
You can use the `success` and `error` output variables of the Apex Action to render success or failure screens.
181-
Add a Decision element that leads to "Success" or "Failure" based on whether the `success` variable is true or
182-
false. In this example, depending on whether the verification is successful, a different screen is presented.
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.
183171

184172
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
185173
<img src="/img/salesforce-flow-decision.png" alt="Configuration of a Decision Flow element" />
186174
<figcaption><i>Configuration of a Decision Flow element</i></figcaption>
187175
</figure>
188176

189-
You can also conditionally render the error message if it's present:
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:
190178

191179
<figure style={{ textAlign: 'center', margin: '3em 0' }}>
192180
<img src="/img/salesforce-flow-error.png" alt="Conditionally display an error message" />
193181
<figcaption><i>Conditionally display an error message</i></figcaption>
194182
</figure>
195183

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+
196227
[appexchange]: #
197228
[fc]: https://friendlycaptcha.com
198229
[fcdocs]: https://developer.friendlycaptcha.com/docs/v2/getting-started
199230
[html]: https://developer.friendlycaptcha.com/docs/v2/getting-started/install#option-a-html-scripts
200231
[sitekey-instructions]: /docs/v2/getting-started/setup
201232
[apikey-instructions]: /docs/v2/api/authentication#creating-api-keys
202-
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)**

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

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# ErrorCodes Class
2+
3+
ErrorCodes contains constants representing various error codes used in the Friendly Captcha SDK.
4+
5+
## Fields
6+
### `FAILED_TO_ENCODE_REQUEST`
7+
8+
(-1, internal) Failed to encode request
9+
10+
#### Signature
11+
```apex
12+
global static final FAILED_TO_ENCODE_REQUEST
13+
```
14+
15+
#### Type
16+
String
17+
18+
---
19+
20+
### `REQUEST_FAILED`
21+
22+
(-1, internal) Failed to talk to the Friendly Captcha API
23+
24+
#### Signature
25+
```apex
26+
global static final REQUEST_FAILED
27+
```
28+
29+
#### Type
30+
String
31+
32+
---
33+
34+
### `FAILED_DUE_TO_CLIENT_ERROR`
35+
36+
(-1, internal) Verification failed due to a client error (check your credentials)
37+
38+
#### Signature
39+
```apex
40+
global static final FAILED_DUE_TO_CLIENT_ERROR
41+
```
42+
43+
#### Type
44+
String
45+
46+
---
47+
48+
### `FAILED_TO_DECODE_RESPONSE`
49+
50+
(-1, internal) Verification failed because we got an unexpected value from the server
51+
52+
#### Signature
53+
```apex
54+
global static final FAILED_TO_DECODE_RESPONSE
55+
```
56+
57+
#### Type
58+
String
59+
60+
---
61+
62+
### `AUTH_REQUIRED`
63+
64+
(401) You forgot to set the X-API-Key header
65+
66+
#### Signature
67+
```apex
68+
global static final AUTH_REQUIRED
69+
```
70+
71+
#### Type
72+
String
73+
74+
---
75+
76+
### `AUTH_INVALID`
77+
78+
(401) The API key you provided is invalid
79+
80+
#### Signature
81+
```apex
82+
global static final AUTH_INVALID
83+
```
84+
85+
#### Type
86+
String
87+
88+
---
89+
90+
### `SITEKEY_INVALID`
91+
92+
(400) The sitekey in your request is invalid
93+
94+
#### Signature
95+
```apex
96+
global static final SITEKEY_INVALID
97+
```
98+
99+
#### Type
100+
String
101+
102+
---
103+
104+
### `RESPONSE_MISSING`
105+
106+
(400) The response field is missing in your request
107+
108+
#### Signature
109+
```apex
110+
global static final RESPONSE_MISSING
111+
```
112+
113+
#### Type
114+
String
115+
116+
---
117+
118+
### `RESPONSE_INVALID`
119+
120+
(200) The response field is invalid
121+
122+
#### Signature
123+
```apex
124+
global static final RESPONSE_INVALID
125+
```
126+
127+
#### Type
128+
String
129+
130+
---
131+
132+
### `RESPONSE_TIMEOUT`
133+
134+
(200) The response has expired
135+
136+
#### Signature
137+
```apex
138+
global static final RESPONSE_TIMEOUT
139+
```
140+
141+
#### Type
142+
String
143+
144+
---
145+
146+
### `RESPONSE_DUPLICATE`
147+
148+
(200) The response has already been used
149+
150+
#### Signature
151+
```apex
152+
global static final RESPONSE_DUPLICATE
153+
```
154+
155+
#### Type
156+
String
157+
158+
---
159+
160+
### `BAD_REQUEST`
161+
162+
(400) Something else is wrong with your request, e.g. the request body was empty
163+
164+
#### Signature
165+
```apex
166+
global static final BAD_REQUEST
167+
```
168+
169+
#### Type
170+
String

0 commit comments

Comments
 (0)