Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

npm install @capgo/capacitor-recaptcha
npx cap sync

Quickstart

Site-Keys konfigurieren in capacitor.config.ts erst, dann eine Aktion ausführen und den Token auf dem Backend verifizieren.

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

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

Häufige Stolperfallen

• Server-Verifizierung: Tokens sind kurzlebig; validiere sie bei Google, bevor du Clients vertraust.
• Schlüssel: Plattformspezifische Site Keys in der Config setzen.
• Enterprise-Flag: müssen mit dem Key-Typ in Google Cloud übereinstimmen.

Site Keys konfigurieren

Erstelle Plattform-Keys in Google Cloud reCAPTCHA und füge sie dann zu 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, und webSiteKey die gemeinsame Einstellung überschreiben siteKey. Du kannst auch einen siteKey direkt an load() oder execute() wenn der Key von deiner Umgebung abhängt.

Token generieren

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() ruft load() automatisch auf, wenn der Client noch nicht bereit ist; ein expliziter Preload-Schritt ist also optional.

Web-Standard reCAPTCHA v3

Setzen Sie enterprise: false zum Laden des Standard-Web-reCAPTCHA-v3-Skripts von Google.

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

Auf Android und iOS ist der native mobile SDK-Pfad von Google nur für Enterprise/mobile verfügbar. Übergeben enterprise: false auf nativen Plattformen wird abgelehnt, damit ein Standard-Web-v3-Key nicht versehentlich verwendet wird.

Migrationshinweise

Das Plugin akzeptiert die alten Cordova-Option-Aliase sitekeyAndroid und sitekeyWeb in den Call-Optionen und der Capacitor-Konfiguration. Es akzeptiert auch sitekeyIos und sitekeyIOS als iOS-Migrations-Aliase. Verwenden Sie für neue code bevorzugt die Capacitor-Konfigurationsnamen.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit Nutzung von @capgo/capacitor-recaptcha für die native Funktion in „Verwendung von @capgo/capacitor-recaptcha“, @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung.