capacitor-recaptcha-v3

reCAPTCHA Enterprise Capacitor Plugin

This plugin provides reCAPTCHA Enterprise functionality for Capacitor applications on iOS and Android platforms. It's based on the Google Cloud reCAPTCHA Enterprise React Native module.

Features

• ✅ iOS and Android support
• ✅ TypeScript support
• ✅ Promise-based API
• ✅ Built-in action types (LOGIN, SIGNUP)
• ✅ Custom action support
• ✅ Timeout configuration
• ✅ Error handling

Install

npm install capacitor-recaptcha-v3
npx cap sync

Setup

iOS Setup

1. Add the following to your ios/App/Podfile:

use_frameworks! :linkage => :static

# Disable Flipper for static linking compatibility
flipper_config = FlipperConfiguration.disabled

2. Run pod install:

cd ios && pod install && cd ..

Android Setup

No additional setup required for Android.

Usage

Basic Usage

import { CapacitorRecaptchaV3, RecaptchaAction } from 'capacitor-recaptcha-v3';

// Fetch a reCAPTCHA client
const client = await CapacitorRecaptchaV3.fetchClient('your-site-key-here');

// Execute reCAPTCHA with login action
const token = await client.execute(RecaptchaAction.LOGIN());
console.log('Token:', token);

Using Different Actions

// Built-in actions
const loginToken = await client.execute(RecaptchaAction.LOGIN());
const signupToken = await client.execute(RecaptchaAction.SIGNUP());

// Custom actions
const purchaseToken = await client.execute(RecaptchaAction.custom('purchase'));
const commentToken = await client.execute(RecaptchaAction.custom('comment'));

With Timeout

// Execute with 10 second timeout
const token = await client.execute(RecaptchaAction.LOGIN(), 10000);

Error Handling

try {
  const client = await CapacitorRecaptchaV3.fetchClient('your-site-key-here');
  const token = await client.execute(RecaptchaAction.LOGIN());
  console.log('Success:', token);
} catch (error) {
  console.error('Error:', error);
}

Deprecated Methods (for backward compatibility)

// Initialize client (deprecated)
const initResult = await CapacitorRecaptchaV3.initClient('your-site-key-here', 5000);

// Execute directly (deprecated)
const token = await CapacitorRecaptchaV3.execute(RecaptchaAction.LOGIN(), 5000);

API

• fetchClient(...)
• initClient(...)
• execute(...)
• Interfaces

fetchClient(...)

fetchClient({ siteKey }: { siteKey: string; }) => Promise<RecaptchaClient>

Fetches a reCAPTCHA client immediately

| Param | Type | Description | | --------- | --------------------------------- | ------------------------------------- | | __0 | { siteKey: string; } | Your application's reCAPTCHA site key |

Returns: Promise<RecaptchaClient>

initClient(...)

initClient({ siteKey, timeout }: { siteKey: string; timeout?: number; }) => Promise<void>

Initialize a reCAPTCHA client

| Param | Type | Description | | --------- | --------------------------------------------------- | ------------------------------------- | | __0 | { siteKey: string; timeout?: number; } | Your application's reCAPTCHA site key |

execute(...)

execute({ action, timeout }: { action: string; timeout?: number; }) => Promise<{ token: string; }>

Execute reCAPTCHA and retrieve a token

| Param | Type | Description | | --------- | -------------------------------------------------- | ------------------------------------------------------------------- | | __0 | { action: string; timeout?: number; } | An action string to describe what the user is doing such as "login" |

Returns: Promise<{ token: string; }>

Interfaces

RecaptchaClient

| Method | Signature | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | execute | (action: RecaptchaAction, timeout?: number | undefined) => Promise<string> |

RecaptchaAction

| Prop | Type | | ------------ | ------------------- | | action | string |

Development

Building

npm run build

Testing

npm run verify

Linting

npm run lint

Common Issues

iOS Build Issues

If you encounter build issues on iOS, make sure:

1. You're using static linking in your Podfile
2. Flipper is disabled
3. You've run pod install after adding the plugin

Android Build Issues

If you encounter build issues on Android, make sure:

1. Your Android SDK is properly configured
2. You've synced the project with npx cap sync

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT

Acknowledgments

This plugin is based on the Google Cloud reCAPTCHA Enterprise React Native module.