@capgo/capacitor-recaptcha

Capacitor plugin for generating reCAPTCHA tokens on Web, Android, and iOS.

It supports:

• Web reCAPTCHA v3 with api.js
• Web reCAPTCHA Enterprise with enterprise.js
• Android and iOS reCAPTCHA Enterprise/mobile SDKs

Use it before sensitive actions such as login, signup, checkout, password reset, or abuse-prone form submissions. The token must be sent to your backend and verified by creating a reCAPTCHA assessment.

The major version of this plugin follows the major version of Capacitor.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-recaptcha` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-recaptcha
npx cap sync

import type { CapacitorConfig } from '@capacitor/cli';
import '@capgo/capacitor-recaptcha';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    Recaptcha: {
      androidSiteKey: 'ANDROID_SITE_KEY',
      iosSiteKey: 'IOS_SITE_KEY',
      webSiteKey: 'WEB_SITE_KEY',
      enterprise: true,
    },
  },
};

export default config;

You can also pass siteKey directly to load() or execute() when the key is environment-specific.

import { Recaptcha } from '@capgo/capacitor-recaptcha';

await Recaptcha.load();

const { token } = await Recaptcha.execute({
  action: 'login',
});

await fetch('/api/recaptcha-assessment', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ token, action: 'login' }),
});

For regular Web reCAPTCHA v3:

const { token } = await Recaptcha.execute({
  siteKey: 'WEB_V3_SITE_KEY',
  enterprise: false,
  action: 'signup',
});

Create an Android mobile application key in Google Cloud reCAPTCHA and use it as androidSiteKey or siteKey.

Android uses Google's mobile reCAPTCHA SDK. Regular, non-Enterprise reCAPTCHA v3 is only available on Web in this plugin; enterprise: false is rejected on Android.

The plugin depends on:

com.google.android.recaptcha:recaptcha:18.8.0

Google's Android reCAPTCHA SDK requires core library desugaring in the consuming app. The plugin enables it automatically during npx cap sync android and adds:

com.android.tools:desugar_jdk_libs:2.1.5

You can override the version from your app Gradle config with recaptchaVersion. You can override the desugaring dependency with desugarJdkLibsVersion.

Create an iOS mobile application key in Google Cloud reCAPTCHA and use it as iosSiteKey or siteKey.

iOS uses Google's RecaptchaEnterprise mobile SDK. Regular, non-Enterprise reCAPTCHA v3 is only available on Web in this plugin; enterprise: false is rejected on iOS.

The plugin ships both Swift Package Manager and CocoaPods metadata and depends on Google's RecaptchaEnterprise iOS SDK.

Use a website key. Set enterprise: true for reCAPTCHA Enterprise or enterprise: false for regular reCAPTCHA v3.

• Tokens are single-use and should be generated immediately before the protected backend request.
• Validate every token on your backend by creating a reCAPTCHA assessment.
• The old Cordova sitekeyAndroid and sitekeyWeb option names are accepted as migration aliases in call options and Capacitor config.
• sitekeyIos and sitekeyIOS are accepted as iOS migration aliases in call options and Capacitor config.

The example-app/ folder links to the local plugin with file:...

cd example-app
npm install
npm run start

• load(...)
• execute(...)
• getPluginVersion()
• Interfaces

reCAPTCHA plugin API.

load(options?: LoadOptions | undefined) => Promise<LoadResult>

Load and cache the reCAPTCHA client for the current platform.

execute() loads the client automatically when needed, so calling this method is optional.

Returns: Promise<LoadResult>

Since: 8.0.0

execute(options: ExecuteOptions) => Promise<ExecuteResult>

Execute reCAPTCHA for an action and return a token for backend assessment.

Returns: Promise<ExecuteResult>

Since: 8.0.0

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Result returned after the client is loaded.

Options used to load the reCAPTCHA client.

Result returned after executing a protected action.

Options used to execute a protected action.

Plugin version payload.