快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

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

然后使用以下 prompt：

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

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

npm install @capgo/capacitor-recaptcha
npx cap sync

快速入门

首先在以下位置配置 site keys， capacitor.config.ts 然后执行操作并在您的后端验证 token。

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

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

常见坑点

• 服务端验证：Token 有效期很短，信任客户端前请先向 Google 验证。
• 密钥：在配置中为每个平台设置 Site Key。
• Enterprise 标记：必须与 Google Cloud 中的密钥类型一致。

配置 Site Keys

在 Google Cloud reCAPTCHA 中创建平台密钥，然后将其添加到 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，以及 webSiteKey 覆盖共享的 siteKey. 您也可以直接传递 siteKey 到 load() 或 execute() 当密钥取决于您的环境时。

生成 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() 调用 load() 在客户端未就绪时自动执行，因此显式的预加载步骤是可选的。

Web 标准版 reCAPTCHA v3

设置 enterprise: false 以加载 Google 标准的 Web reCAPTCHA v3 脚本。

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

在 Android 和 iOS 上，Google 原生的移动端 SDK 路径仅限 Enterprise/mobile 使用。通过 enterprise: false 原生平台进行传递会被拒绝，以防止误用标准的 Web v3 密钥。

迁移说明

该插件支持旧版的 Cordova 选项别名 sitekeyAndroid 以及 sitekeyWeb （位于调用选项和 Capacitor 配置中）。它还支持 sitekeyIos 以及 sitekeyIOS 作为 iOS 迁移别名。对于新的 code，请优先使用 Capacitor 配置名称。

从入门指南继续

如果你正在使用 快速入门 用来规划身份验证和账户流程，并将它与 使用 @capgo/capacitor-recaptcha 在使用 @capgo/capacitor-recaptcha 时，用于原生能力 @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。