@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.

Compatibility

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

Install

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

Configuration

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.

Usage

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',
});

Platform Setup

Android

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.

iOS

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.

Web

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

Notes

• 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.

Example App

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

cd example-app
npm install
npm run start

API

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

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

getPluginVersion() => Promise<PluginVersionResult>