Zum Hauptinhalt springen

Integration mit JavaScript und PHP

Erfahre, wie du POWER CAPTCHA mit JavaScript in dein bestehendes Formular integrierst und das Token mit PHP verifizieren kannst.

Nachdem du deinen API-Key erstellt und konfiguriert hast, kannst du direkt loslegen und POWER CAPTCHA in dein Formular integrieren.

Die Integration besteht aus zwei Schritten:

  1. Die Einbindung des POWER CAPTCHA Widgets in dein Formular
  2. Die Verifizierung des Tokens nach dem Absenden des Formulars

Einbindung in dein Formular​

JavaScript hinzufügen​

Füge unser JavaScript auf der Seite ein, auf der das Formular dargestellt wird:

<script src="https://cdn.power-captcha.com/v1/power-captcha-1.2.8.min.js" type="text/javascript" defer></script>

Das JavaScript kann sowohl im <head>-Element als auch am Ende der Seite (vor dem </body>-Element) eingefügt werden.

Widget einbinden​

Füge innerhalb des zu schützenden Formulars folgendes <div>-Element hinzu und ersetze die Platzhalter in den Attributen data-pc-api-key und data-pc-client-uid. Innerhalb des <div>-Elements wird das POWER CAPTCHA-Widget dargestellt.

<form>
     ...
     <div data-pc-api-key="<apiKey>"
          data-pc-client-uid="<eindeutigeClientId>">
     </div>
     ...
</form>
Platzhalter <apiKey> ersetzen​

Der Platzhalter <apiKey> muss mit deinem API-Key ersetzt werden.

Platzhalter <eindeutigeClientId> ersetzen​

Der Platzhalter <eindeutigeClientId> muss durch einen dynamischen Wert ersetzt werden, über den der Client eindeutig identifiziert werden kann. Dies kann zum Beispiel die IP-Adresse des Clients sein. Wichtig ist, dass derselbe Wert auch bei der Verifizierung des Tokens übergeben wird.

Hier ein Beispiel, wie die Client-ID basierend auf der IP-Adresse mit PHP generiert werden kann:

data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>"
Verwendung eines Reverse-Proxy

Wenn deine Website hinter einem Reverse-Proxy betrieben wird, gibt $_SERVER['REMOTE_ADDR'] möglicherweise nicht die IP-Adresse des Clients zurück. Stattdessen wird die IP-Adresse des Clients je nach Konfiguration des Proxies in bestimmten Headern übermittelt, oft in X-Forwarded-For oder X-Real-IP. In PHP können diese Header mit $_SERVER['HTTP_X_FORWARDED_FOR'] bzw. $_SERVER['HTTP_X_REAL_IP'] ausgelesen werden.

Zusätzlicher Schutz eines Input-Felds (optional, nur Enterprise-Tarif)​

Falls du einen Enterprise-Tarif hast, kannst du für zusätzlichen Schutz ein Input-Feld (z.B. Benutzername / E-Mail-Adresse) mit POWER CAPTCHA sichern. Dazu muss das Input-Feld mit dem Attribut data-pc-user versehen werden. Darüber erkennt unser JavaScript, welches Feld geschützt werden soll. Beispiel:

<input name="username" type="text" required data-pc-user="" />

Bitte beachte, dass der Wert des Input-Felds bei der Token-Verifizierung unverändert übertragen werden muss.

Beispiel Login-Formular mit PHP und HTML​

Ein einfaches Login-Formular, welches mit POWER CAPTCHA geschützt wird, könnte beispielsweise so aussehen:

<form method="post" action="submit.php">
    <label for="username">Username:</label><br />
    <input type="text" id="username" name="username" required data-pc-user="" /><br />
    <label for="password">Password:</label><br />
    <input type="password" id="password" name="password" />
    <div data-pc-api-key="<apiKey>"
         data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>">
    </div>
    <input type="submit" value="submit" />
</form>

Weitere Einstellungs- und Einbindungsmöglichkeiten​

Weitere Optionen und Einstellungsmöglichkeiten (z.B. Prüfmodus / Widget verstecken) findest du hier unter Konfiguration des Widgets.

Token-Verifizierung im Backend​

Das Widget fügt deinem Formular automatisch ein unsichtbares Input-Feld pc-token hinzu. Dieses Feld enthält ein Token, das du in deinem Backend verifizieren kannst.

Darüber kannst du sicherstellen, dass der Zugriff überprüft wurde und berechtigt ist (z.B. ob das Captcha ordnungsgemäß gelöst wurde).

Prüfen, ob das Input-Feld pc-token gefüllt ist​

Vor der eigentlichen Verifizierung sollte geprüft werden, ob das Input-Feld pc-token vorhanden ist und gefüllt wurde. Ist dies nicht der Fall, wurde vor dem Absenden des Formulars kein Token generiert und der Zugriff ist somit unberechtigt.

<?php
if(!isset($_POST['pc-token']) || empty($_POST['pc-token'])) {
    // Abbruch, da kein Token vorhanden
    die("Kein Captcha-Token vorhanden.");
    // Alternativ kannst du hier auch eine erweiterte Fehlerbehandlung einfügen
}
// Fortfahren mit der Token-Verifizierung

Anfrage an die Verifikations-API​

Die Verifizierung erfolgt über unsere API (https://api.power-captcha.com/pcu/v1/verify). An diese Schnittstelle müssen einige Parameter, wie z.B. der Feld-Inhalt aus pc-token, als JSON-Body per POST gesendet werden.

Innerhalb von PHP kann die Schnittstelle per cURL aufgerufen werden.

cURL initialisieren​

Dazu muss curl zunächst initialisiert werden. Hierbei ist es wichtig, dass im HTTP-Header das Feld X-API-Key mit deinem API-Key belegt wird. Außerdem muss der Content-Type auf application/json gesetzt sein.

$curl = curl_init('https://api.power-captcha.com/pcu/v1/verify');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE);

curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: <apiKey>', // Dein API-Key
    'Content-Type: application/json'
));

Der Platzhalter <apiKey> muss mit deinem API-Key ersetzt werden.

JSON-Body erstellen​

Den JSON-Body mit den Parametern für die Verifizierung kannst du über ein array und die PHP-Methode json_encode generieren.

$json_body = json_encode(
    array(
        'secret' => '<secretKey>', // Dein Secret-Key
        'token' => $_POST['pc-token'], // Inhalt des Token-Felds
        'clientUid' => hash('sha256', $_SERVER['REMOTE_ADDR']), // eindeutige Client ID (selber Wert wie im data-client-uid Attribut)
        'name' => $_POST['username'] // Unveränderter Wert des Feldes, das mit 'data-pc-user' markiert wurde (optional, nur Enterprise-Tarif)
    )
);

Der Platzhalter <secretKey> muss mit deinem Secret-Key ersetzt werden.

Detaillierte Informationen zum Aufbau des JSONs sowie zu den Parametern findest du unter Verifizierung des Tokens.

Anfrage absenden​

Den $json_body kannst du nun als POST-Anfrage in curl setzen:

curl_setopt($curl, CURLOPT_POSTFIELDS, $json_body);

Im Anschluss kannst du die Verifizierungs-Anfrage per curl_exec an unsere API übermitteln. Die Antwort wird per json_decode dekodiert und als Objekt zur Verfügung gestellt.

$response = json_decode(
    curl_exec($curl)
);

Bevor du die Antwort auswertest, solltest du curl_close aufrufen, um die Verbindung zu beenden.

curl_close($curl);

Auswertung der Antwort​

In der Variable $response steht das Ergebnis der Verifizierung. Hier ist vor allem das Feld success relevant, welches angibt, ob die Token-Verifizierung erfolgreich war und das Token gültig ist.

Mit folgendem Code wird das Ergebnis geprüft. Wenn $response->success == true ist, also das Token gültig ist, kannst du mit der Verarbeitung deines Formulars fortfahren. Andernfalls (Token ungültig oder Fehler bei der Verifizierung) wird die Ausführung abgebrochen.

if($response->success) {
    // Verifizierung erfolgreich und Token gültig
    // Hier kannst du deinen Code für die weitere Verarbeitung deines Formulars einfügen
} else {
    // Abbruch, da Token ungültig oder Fehler bei der Verifizierung
    die("Fehler: Captcha-Token ungültig oder Verifizierung fehlgeschlagen.");
    // Alternativ kannst du hier auch eine erweiterte Fehlerbehandlung einfügen
}

Eine nicht erfolgreiche Verifizierung ($response->success == false) kann verschiedene Ursachen haben. Weitere Informationen dazu findest du unter Verifizierung des Tokens.

Vollständiger Beispiel-Code​

<?php
// Prüfen, ob das Input-Feld pc-token gefüllt ist
if(!isset($_POST['pc-token']) || empty($_POST['pc-token'])) {
    // Abbruch, da kein Token vorhanden
    die("Kein Captcha-Token vorhanden.");
    // Alternativ kannst du hier auch eine erweiterte Fehlerbehandlung einfügen
}

// curl initialisieren
$curl = curl_init('https://api.power-captcha.com/pcu/v1/verify');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE);

curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: <apiKey>', // Dein API-Key
    'Content-Type: application/json'
));

$json_body = json_encode(
    array(
        'secret' => '<secretKey>', // Dein Secret-Key
        'token' => $_POST['pc-token'], // Inhalt des Token-Felds
        'clientUid' => hash('sha256', $_SERVER['REMOTE_ADDR']), // eindeutige Client ID (selber Wert wie im data-client-uid Attribut)
        'name' => $_POST['username'] // Unveränderter Wert des Feldes, was mit 'data-pc-user' markiert wurde (optional, nur Enterprise-Tarif)
    )
);

// JSON-Body als POST-Anfrage setzen
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_body);

// Anfrage absenden
$response = json_decode(
    curl_exec($curl)
);
curl_close($curl);

// Antwort auswerten
if($response->success) {
    // Verifizerung erfolgreich und Token gültig
    // Hier kannst du deinen Code für die weitere Verarbeitung deines Formulars einfügen
} else {
    // Abbruch, da Token ungültig oder Fehler bei der Verifizerung
    die("Fehler: Captcha-Token ungültig oder Verifizierung fehlgeschlagen.");
    // Alternativ kannst du hier auch eine erweiterte Fehlerbehandlung einfügen
}