Getting Started

Install

npm install @capgo/capacitor-recaptcha
npx cap sync

Configure Site Keys

Create platform keys in Google Cloud reCAPTCHA, then add them to capacitor.config.ts.

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;

androidSiteKey, iosSiteKey, and webSiteKey override the shared siteKey. You can also pass a siteKey directly to load() or execute() when the key depends on your environment.

Generate A Token

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

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

execute() calls load() automatically when the client is not ready, so an explicit preload step is optional.

Web Standard reCAPTCHA v3

Set enterprise: false to load Google’s standard Web reCAPTCHA v3 script.

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

On Android and iOS, Google’s native mobile SDK path is Enterprise/mobile only. Passing enterprise: false on native platforms is rejected so a standard Web v3 key is not used accidentally.

Migration Notes

The plugin accepts the old Cordova option aliases sitekeyAndroid and sitekeyWeb in call options and Capacitor config. It also accepts sitekeyIos and sitekeyIOS as iOS migration aliases. Prefer the Capacitor config names for new code.