--- title: Integrating reCAPTCHA Enterprise into a JavaScript app description: PingOne Advanced Identity Cloud PingAM JavaScript component: orchsdks page_id: orchsdks:journey:use-cases/recaptcha-enterprise/javascript-recaptcha-enterprise canonical_url: https://developer.pingidentity.com/orchsdks/journey/use-cases/recaptcha-enterprise/javascript-recaptcha-enterprise.html section_ids: prerequisites: Prerequisites callback: Handling the callback with the SDK config: Configuring the verification payload: Customizing the assessment payload custom-error: Returning custom error codes --- # Integrating reCAPTCHA Enterprise into a JavaScript app [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: js, set=fab]JavaScript To add support for reCAPTCHA Enterprise to your JavaScript apps, complete the following tasks. ## Prerequisites In a JavaScript app you must complete the following steps before using reCAPTCHA Enterprise: 1. Load Google's reCAPTCHA Enterprise JavaScript API JavaScript file in the `HEAD` of your app. You'll need to add your site key as a parameter when loading the script: ```html ... ``` To learn more, refer to [Install score-based keys on websites](https://cloud.google.com/recaptcha/docs/instrument-web-pages) in the *Google Cloud documentation*. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can get the URI to the JavaScript file, and site key value from the `ReCaptchaEnterpriseCallback`, if you want to dynamically load the reCAPTCHA script.Use the `callback.getApiUrl()` and `callback.getSiteKey()` methods if you want to dynamically load the reCAPTCHA API.```typescript // Handling 'ReCaptchaEnterpriseCallback' const callback = step.getCallbackOfType('ReCaptchaEnterpriseCallback') // Get the URI to the reCAPTCHA JavaScript file from the callback const apiUrl = callback.getApiUrl(); // Get the site key from the callback const siteKey = callback.getSiteKey(); ``` | 2. Retrieve a `reCAPTCHA_Enterprise_Token`. You'll need to return this to the server when [Handling the callback with the SDK](#callback). To learn more, refer to [Retrieve a token](https://cloud.google.com/recaptcha/docs/create-assessment-website#retrieve-token) in the *Google Cloud documentation*. ## Handling the callback with the SDK Use code similar to the following to handle the `ReCaptchaEnterpriseCallback` in your client-side code using the Orchestration SDKs: Return the `reCAPTCHA_Enterprise_Token` you obtained earlier as follows: ```typescript // Handling 'ReCaptchaEnterpriseCallback' const callback = step.getCallbackOfType('ReCaptchaEnterpriseCallback') // Set provider on the callback callback.setResult(reCAPTCHA_Enterprise_Token); // Submit the current step and get the next one step = await journeyClient.next(step); ``` ## Configuring the verification You can configure the type of action being performed in the call to `verify()`: Configuring the call to `verify()` on JavaScript ```typescript // Handling 'ReCaptchaEnterpriseCallback' const callback = step.getCallbackOfType('ReCaptchaEnterpriseCallback') // Set provider on the callback callback.setAction("LOGIN"); // Set provider on the callback callback.setResult(reCAPTCHA_Enterprise_Token); // Submit the current step and get the next one step = await journeyClient.next(step); ``` The available properties for the action value are as follows: * `LOGIN` For login journeys * `SIGNUP` For registration journeys Or you can specify your own action, as a string value. ``` callback.setAction("PASSWORD_RESET") callback.setAction("PAYMENT") callback.setAction("ADD_TO_CART") ``` ## Customizing the assessment payload You can add additional data to customize the payload that the server sends to the Google reCAPTCHA Enterprise for assessment. Add data to the payload to leverage additional functionality provided by reCAPTCHA Enterprise. The JSON format the payload expects is as follows: ```json { "token": string, "siteKey": string, "userAgent": string, "userIpAddress": string, "expectedAction": string, "hashedAccountId": string, "express": boolean, "requestedUri": string, "wafTokenAssessment": boolean, "ja3": string, "headers": [ string ], "firewallPolicyEvaluation": boolean, "transactionData": { object (TransactionData) }, "userInfo": { object (UserInfo) }, "fraudPrevention": enum (FraudPrevention) } ``` By default, the SDK or the node itself populates the following fields: * `token` * `siteKey` * `userAgent` * `userIpAddress` * `expectedAction` You can however also override these values if it suits your use case. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can add custom payload data as part of an authentication journey that includes the [reCAPTCHA Enterprise node](https://docs.pingidentity.com/auth-node-ref/latest/recaptcha-enterprise.html). Custom data in the journey overrides any custom data added by the client. | To learn more about the payload, refer to [Project Assessments - Event](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments#event) in the Google Developer documentation. To customize data for an assessment, use the `setPayload()` method: ```javascript // Optional payload values for customization callback.setPayload({ "firewallPolicyEvaluation": false }); ``` ## Returning custom error codes You can return a custom error to the node if required for your business logic: ```javascript // Optional custom error code callback.setClientError('custom_client_error'); ```