@capgo/capacitor-recaptcha

Protect sign-ups, logins and payments in your Capacitor app with reCAPTCHA tokens on web, Android and iOS, verified by your backend.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-recaptcha in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-recaptcha to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Load: load() initializes and caches the reCAPTCHA client.
• Execute: execute() returns a token for an action, ready for backend verification.
• Mobile: reCAPTCHA Enterprise SDKs on Android and iOS.
• Web: reCAPTCHA v3 with api.js, or reCAPTCHA Enterprise with enterprise.js.
• Per-platform keys: androidSiteKey, iosSiteKey and webSiteKey win over the shared siteKey set at the same level.
• Platforms: iOS, Android and Web.

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(...)
• execute(...)
• getPluginVersion()
• Interfaces

reCAPTCHA plugin API.

load(...)

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(...)

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()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Interfaces

LoadResult

Result returned after the client is loaded.

LoadOptions

Options used to load the reCAPTCHA client.

ExecuteResult

Result returned after executing a protected action.

ExecuteOptions

Options used to execute a protected action.

PluginVersionResult

Plugin version payload.