Adding Captcha Protection

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Summary

Setting up a captcha can help protect your Dynamic-enabled site from bots. Dynamic supports two captcha providers:

• Cloudflare Turnstile — Dynamic manages the keys for you by default, or bring your own site key and secret key.
• hCaptcha — Bring your own site key and secret key.

Setting up Cloudflare Turnstile

Dynamic manages Turnstile keys by default — no Cloudflare account required. By default, Dynamic uses the managed widget type, which lets Cloudflare automatically select the best challenge experience for each visitor.

1. Log in to Dynamic Dashboard. On the left navigation bar, click on “Fraud Protections” then select “Captcha”.
2. Select Cloudflare Turnstile as your provider.
3. (Optional) Enter your own site key and secret key if you want to use your own Cloudflare Turnstile account. Bringing your own credentials is required if you want to customize widget settings such as the widget type.
4. Enable — Toggle captcha on when you are ready.

Setting up your own Cloudflare Turnstile account

If you want to bring your own credentials (for example, to control the widget type or other settings):

1. Sign up for a Cloudflare account at cloudflare.com if you don’t have one.
2. Navigate to Turnstile in the Cloudflare dashboard sidebar.
3. Add a new site — Enter a name and the domain(s) where you’ll use the Dynamic SDK. Select your preferred widget type (managed, non-interactive, or invisible).
4. Copy your site key — shown after creating the site.
5. Copy your secret key — shown on the same page. This is used server-side to verify tokens and is never exposed to the SDK.
6. Enter both keys in the Dynamic Dashboard under Fraud Protections → Captcha.

Setting up hCaptcha

To get started, you must first create an hCaptcha account.

1. Sign up for a new account on hCaptcha - We recommend considering upgrading to the “Pro” plan, which allows for “passive” and “friction-free” modes.

2. Add a new site - Make sure the hostname corresponds to the domain you are using the Dynamic SDK on. For example, if you plan to set up the Dynamic SDK in app.myawesomesite.com, then you should add this value to the Hostname sections in hCaptcha.

   

3. Get your site key - This is used by the Dynamic SDK to communicate with hCaptcha and display a captcha challenge before the verification step in the wallet sign-in flow. Copy this value, which we will need to set up in Dynamic.

   

4. Get your secret key - This is used by the Dynamic server-side backend to verify the captcha result from the SDK, and is never leaked to the SDK. To get your secret key, click on your account profile on the upper right corner and select “Settings”. You should see your plaintext secret key, which you should also copy to set up in Dynamic.

   

Setting up Dynamic captcha (hCaptcha)

Now that we have hCaptcha set up, we can move on to final configuration within Dynamic.

1. Log in to Dynamic Dashboard. On the left navigation bar, click on “Fraud Protections” then select “Captcha”.

2. Select hCaptcha as your provider and add your site key and secret key from the previous steps.

3. Enable — When you are ready to enable the captcha, please make sure to switch the “enable” toggle.

Using our UI

Captcha will be automatically enabled in the Dynamic widget when you enable it in the Dynamic dashboard.

Using your UI

The connectWithEmail and connectWithSms methods support an optional captchaToken parameter. If captcha is enabled in our dashboard, you must pass in a captchaToken to the methods.

const { connectWithEmail, connectWithSms } = useConnectWithOtp();

const captchaToken = ... // get the captcha token from your captcha integration

connectWithEmail('[e-mail]', captchaToken);
connectWithSms(phone, captchaToken);

Social Signup/Login with captcha is not yet supported.