Zum Hauptinhalt springen

Eigene Integration

Sie können mosparo problemlos in Ihre eigene Website integrieren. Um mosparo nutzen zu können, brauchen Sie ein Formular, welches eines oder mehrere Formularfelder beinhaltet.

Container einbauen

Fügen Sie in Ihrem Formular an der Stelle, an welcher die mosparo-Box angezeigt werden soll, einen leeren Div-Container ein, welcher mit einem ID-Attribut versehen ist:

<div id="mosparo-box"></div>

CSS-Ressourcen einbinden

Im Kopf Ihrer Website müssen Sie die CSS-Ressourcen von mosparo einbinden. Fügen Sie dazu folgenden Code im HTML-Head-Bereich ein:

<link href="https://<host>/resources/<uuid>.css" rel="stylesheet"> 

Ersetzen Sie dabei <host> mit der Adresse Ihrer mosparo-Installation. Tragen Sie bei <uuid> die eindeutige Identifikationsnummer Ihres mosparo-Projektes ein.

Information

Sie können die CSS-Ressourcen auch direkt vom Script beim Initialisieren der mosparo-Box einbinden. Verwenden Sie dazu die Option loadCssResource bei der Initialisierung (siehe Parameter der mosparo-Klasse).

JavaScript einbinden

Binden Sie das Script von mosparo auf Ihrer Website ein. Initialisieren Sie danach mosparo mit dem untenstehenden Code.

<script  src="https://<host>/build/mosparo-frontend.js" defer></script>
<script>
var m;
window.onload = function(){
m = new mosparo(
'<htmlId>',
'<host>',
'<uuid>',
'<publicKey>',
<options>
);
};
</script>
Information

Die Kleiner-als- (<) und Grösser-als-Zeichen (>) sind zur Kennzeichnung des Platzhalters eingefügt und müssen mit dem richtigen Wert ersetzt werden.

Parameter der mosparo Klasse

ParameterTypErforderlichBeschreibung
<htmlId>StringErforderlichHTML-ID des Div-Containers, welchen Sie in Ihrem Formular eingefügt haben.
<host>StringErforderlichHost Ihrer mosparo-Installation
<uuid>StringErforderlichEindeutige Identifikationsnummer des Projektes in mosparo
<publicKey>StringErforderlichÖffentlicher Schlüssel des Projektes in mosparo
<options>ObjektOptionalZusätzliche Optionen

Zusätzliche Optionen

ParameterTypStandard-WertBeschreibung
allowBrowserValidationBooleantrueGibt an, ob die Browser-Validierung aktiv sein soll.
cssResourceUrlStringleerDefiniert die Adresse, unter welcher die CSS-Ressourcen geladen werden können. Kann verwendet werden, wenn die korrekte Ressourcenadresse gecached wird.
customMessagesObjekt{}Ermöglicht das überschreiben der Texte in der Frontend-Box (siehe Benutzerdefinierte Texte).
designModeBooleanfalseWird verwendet, um im Backend von mosparo die mosparo-Box in den unterschiedlichen Zuständen darzustellen. Die mosparo-Box ist nicht funktionsfähig, wenn diese Option auf true gesetzt wird.
doSubmitFormInvisibleCallableleer(Nur im unsichtbaren Modus) Mit dieser Methode ist die Ausführung einer benutzerdefinierten Übermittlungsaktion möglich, nachdem das Formular validiert wurde (z. B. durch XHR). Dadurch wird der Standardübermittlungsprozess übersprungen.
inputFieldSelectorString[name]:not(.mosparo__ignored-field)Definiert den Selektor, mit welchem die Felder gesucht werden.
languageStringleerLegt die Sprache der mosparo-Box fest. Das Feld ist standardmässig leer, dass heisst, mosparo verwendet die vom Browser definierte Sprache (falls vorhanden) oder Englisch. Wenn die Übersetzung für die definierte Sprache nicht vorhanden ist, antwortet mosparo mit der englischen Übersetzung. Beispiel: fr_FR. (Hinzugefügt in v1.1)
loadCssResourceBooleanfalseBestimmt, ob bei der Initialisierung auch die CSS-Ressourcen geladen werden sollen (siehe CSS-Ressourcen einbinden).
nameStringleerDefiniert den Namen der HTML-Checkbox. Standardmässig wird eine zufällige ID dafür verwendet.
onAbortSubmitCallableleer(Nur im sichtbaren Modus) Dieser Callback wird aufgerufen, nachdem der Absendevorgang abgebrochen wurde, z.B. wenn das Formular von mosparo erneut validiert werden muss.
onCheckFormCallableleerDefiniert einen Callback, der aufgerufen wird, sobald das Formular geprüft wurde. Das Überprüfungsergebnis wird als boolescher Parameter an den Callback übergeben (true wenn alles korrekt ist, false wenn nicht).
onResetStateCallableleerDefiniert einen Callback, der ausgeführt wird, nachdem die mosparo Box zurückgesetzt wurde (z.B. nachdem das Formular zurückgesetzt wurde).
onSwitchToInvisibleCallableleer(Nur im unsichtbaren Modus) Wenn eine Website den unsichtbaren Modus verwendet, initialisiert sich mosparo im sichtbaren Modus und wechselt nach Erhalt des Einsende-Codes in den unsichtbaren Modus. Dieser Callback wird nach dem Wechsel in den unsichtbaren Modus aufgerufen.
onSubmitFormInvisibleCallableleer(Nur im unsichtbaren Modus) Dieser Callback wird aufgerufen, bevor das Formular abgeschickt wird.
onValidateFormInvisibleCallableleer(Nur im unsichtbaren Modus) Dieser Callback wird aufgerufen, bevor das Formular validiert wird.
requestSubmitTokenOnInitBooleantrueGibt an, ob bei der Initialisierung automatisch ein Einsendecode angefordert werden soll. Wenn zum Beispiel direkt nach der Initialisierung des Formulars das Formular zurückgesetzt wird (mit reset()) braucht es bei der Initialisierung keinen Einsendecode, da mit dem Zurücksetzen ein neuer Code angefordert wird.

Benutzerdefinierte Texte

Mit der Option customMessages ist es möglich, die in der Frontend-Box sichtbaren Texte anzupassen. Die Option akzeptiert ein Objekt, wobei der Eigenschaftsname das Gebietsschema und der Wert ein Objekt ist.

In dem Objekt für ein Gebietsschema ist der Eigenschaftsname der Name der Nachricht, während der Wert der übersetzte Text ist (siehe Texte).

Die Funktionalität verwendet die Sprachinformationen des Browsers durch Zugriff auf navigator.languages. Wenn diese Eigenschaft nicht verfügbar ist, wird das Skript die Übersetzungen verwenden, die es vom mosparo-Backend erhalten hat. Alle in der Eigenschaft navigator.languages verfügbaren Gebietsschemata werden getestet, wobei das erste, das übereinstimmt und nicht leer ist, verwendet wird. Wenn ein Bindestrich im Namen des Gebietsschemas enthalten ist (-, zum Beispiel de-CH), wird er durch einen Unterstrich ersetzt (_, zum Beispiel de_CH).

Texte
Text-NameVerwendungszweckStandard-Wert
labelDies ist der Hauptsatz der Box.Ich akzeptiere, dass die Formulareingaben auf Spam überprüft und für 14 Tage verschlüsselt gespeichert werden.
accessibilityCheckingDataDies ist eine Statusaktualisierung, wenn mosparo die Daten überprüft. Sie ist nur für Screen Readers sichtbar.Wir überprüfen Ihre Daten. Bitte warten Sie.
accessibilityDataValidDies ist ein Status-Update, wenn mosparo die Daten überprüft hat und alles in Ordnung ist. Sie ist nur für Screen Readers sichtbar.Ihre Daten enthalten kein Spam. Sie können das Formular absenden.
errorGotNoTokenSichtbar, wenn kein Einsendecode von mosparo zurückgegeben wurde.mosparo hat keinen Absende-Token ausgestellt.
errorInternalErrorSichtbar, wenn mosparo einen internen Fehler hatte.Es trat ein Fehler auf. Bitte wiederholen Sie den Vorgang.
errorNoSubmitTokenAvailableSichtbar, wenn der Einsendecode aus dem Formular entfernt wurde, z. B. weil das Formular manipuliert wurde.Kein Absende-Token verfügbar. Die Validierung Ihrer Daten ist nicht möglich.
errorSpamDetectedWird angezeigt, wenn mosparo Spam in der Einsendung entdeckt hat.In Ihren Daten ist Spam enthalten.
errorLockedOutWird angezeigt, wenn der Benutzer zu viele Einsendungen eingereicht und mosparo den Benutzer ausgesperrt hat.Sie wurden temporär gesperrt. Bitte versuchen Sie es nach %datetime% erneut.
errorDelayWird angezeigt, wenn der Benutzer zu viele Einsendecodes angefordert und daher von mosparo verzögert wurde.Ihre Anfrage wurde verzögert. Bitte warten Sie %seconds% Sekunden.
hpLeaveEmptyDiese Meldung ist versteckt und nur für Screen Readers für das Honeypot-Feld sichtbar.Dieses Feld leer lassen
Beispiel
mosparo('<htmlId>', '<host>', '<uuid>', '<publicKey>', {
customMessages: {
de_CH: {
label: 'Ich akzeptiere aus der Schweiz'
},
en_GB: {
label: 'I accept from United Kingdom'
},
en_AU: {
label: 'I accept from Australia',
errorSpamDetected: 'Spam from Australia? Impossible!'
}
}
});

Ereignisse

Wenn Sie die Initialisierungsparameter nicht anpassen können, können Sie auch die benutzerdefinierten Ereignisse verwenden, um die Ausführung von mosparo zu steuern. Alle Ereignisse werden auf dem Formularelement (<form>) ausgelöst. mosparo löst die folgenden Ereignisse aus:

EreignisnameBeschreibung
form-checkedDefiniert das Ereignis, welches ausgelöst wird, sobald das Formular geprüft wurde. Das Ergebnis der Prüfung wird als boolescher Wert valid an das Ereignis übergeben (true wenn alles korrekt ist, false wenn nicht).
state-resetedDefiniert das Ereignis, welches ausgelöst wird, nachdem das mosparo-Feld zurückgesetzt wurde (zum Beispiel, nachdem das Formular zurückgesetzt wurde).
switch-to-invisibleWenn eine Website den unsichtbaren Modus verwendet, initialisiert sich mosparo im sichtbaren Modus und wechselt nach Erhalt des Einsende-Codes in den unsichtbaren Modus. Dieses Ereignis wird nach dem Wechsel in den unsichtbaren Modus ausgelöst.
submit-aborted(Nur im sichtbaren Modus) Dieses Ereignis wird ausgelöst, wenn der Sendevorgang abgebrochen wird, z.B. wenn das Formular von mosparo erneut validiert werden muss.
submit-form-invisible(Nur im unsichtbaren Modus) Dieses Ereignis wird vor dem Absenden des Formulars ausgelöst.
validate-form-invisible(Nur im unsichtbaren Modus) Dieses Ereignis wird ausgelöst, bevor das Formular validiert wird.

Beispiele für Ereignisse und Callbacks

mosparo('<htmlId>', '<host>', '<uuid>', '<publicKey>', {
onCheckForm: function (valid) {
console.log('onCheckForm', valid);
},
onResetState: function () {
console.log('onResetState');
},
onAbortSubmit: function () {
console.log('onAbortSubmit');
},
onSwitchToInvisible: function () {
console.log('onSwitchToInvisible');
},
onValidateFormInvisible: function () {
console.log('onValidateFormInvisible');
},
onSubmitFormInvisible: function () {
console.log('onSubmitFormInvisible');
}
});

document.getElementById('contact-form').addEventListener('form-checked', function (ev) {
console.log(ev, ev.detail.valid);
});

document.getElementById('contact-form').addEventListener('submit-aborted', function (ev) {
console.log(ev);
});

document.getElementById('contact-form').addEventListener('state-reseted', function (ev) {
console.log(ev);
});

document.getElementById('contact-form').addEventListener('switch-to-invisible', function (ev) {
console.log(ev);
});

document.getElementById('contact-form').addEventListener('validate-form-invisible', function (ev) {
console.log(ev);
});

document.getElementById('contact-form').addEventListener('submit-form-invisible', function (ev) {
console.log(ev);
});

Verifizierung durchführen

Nachdem das Formular abgesendet wurde, muss überprüft werden, ob die Einsendung überhaupt erlaubt war. Rein technisch wäre es vorstellbar, dass jemand zwar die Prüfung von mosparo besteht, danach mit technischen Mitteln die Anfrage wieder verändert und erst dann das Formular absendet. Daher ist es zwingend erforderlich, zu überprüfen, ob die getätigten Eingaben gültig waren.

Vorbereiten der Formulardaten

Aus den eingesendeten Formulardaten müssen alle von mosparo ignorierten Felder entfernt werden (siehe ignorierte Felder).

Verifizieren mit Funktionsbibliothek

Anschliessend können Sie mit der Funktionsbibliothek die Verifizierung durchführen. Dazu benötigen Sie den Host Ihrer mosparo-Installation, den öffentlichen sowie den privaten Schlüssel sowie die bereinigten Formulardaten.

Konsultieren Sie für die genaue Vorgehensweise die Dokumentation der von Ihnen verwendeten Funktionsbibliothek.

Funktionsbibliotheken

Um die Verifizierung auf Ihrer Website zu vereinfachen, gibt es Funktionsbibliotheken, welche die Verifizierung vereinfachen. Falls Sie die Verifizierung ohne Funktionsbibliothek durchführen möchten, siehe Verifizierung manuell durchführen.

NameSpracheGepflegt durchWebsite
JS API clientJavaScriptmosparo Core Developershttps://github.com/mosparo/js-api-client
PHP API clientPHPmosparo Core Developershttps://github.com/mosparo/php-api-client
Python API clientPythonmosparo Core Developershttps://github.com/mosparo/python-api-client

Verifizierung manuell durchführen

Wenn Sie keine Funktionsbibliothek verwenden wollen oder für Ihre Programmiersprache keine Funktionsbibliothek zur Verfügung steht, können Sie die Überprüfung leicht manuell durchführen.

Information

Alle Codebeispiele in diesem Abschnitt sind in der Programmiersprache PHP geschrieben. Dies dient nur der besseren Darstellung. Sie können jede beliebige Programmiersprache verwenden.

Formular

In diesem Beispiel verwenden wir ein einfaches Formular mit einem Feld für den Namen, die E-Mail-Adresse und einem Textfeld für die Nachricht.

<form method="post" id="contact-form">
<div class="row mb-3">
<label class="col-sm-3 col-form-label required" for="name">Name</label>
<div class="col-sm-9">
<input type="text" name="name" id="name" class="form-control" required />
</div>
</div>
<div class="row mb-3">
<label class="col-sm-3 col-form-label required" for="emailAddress">Email address</label>
<div class="col-sm-9">
<input type="email" name="emailAddress" id="emailAddress" class="form-control" required />
</div>
</div>
<div class="row mb-3">
<label class="col-sm-3 col-form-label required" for="message">Message</label>
<div class="col-sm-9">
<textarea class="form-control" name="message" id="message" style="height: 300px;" required></textarea>
</div>
</div>
<div class="row mb-3">
<div class="col-sm-3"></div>
<div class="col-sm-9">
<div id="mosparo-box"></div>
</div>
</div>

<div class="row mb-3">
<div class="col-sm-3"></div>
<div class="col-sm-9">
<button type="submit" name="submitted" class="btn btn-primary btn-lg">
Submit
</button>
</div>
</div>
</form>

<script src="https://mosparo.example.com/build/mosparo-frontend.js" defer></script>
<script>
var m;
window.onload = function(){
m = new mosparo('mosparo-box', 'https://mosparo.example.com', '<uuid>', '<publicKey>', {
loadCssResource: true
});
};
</script>

Vor dem Hinzufügen von mosparo

Nachdem das Formular abgeschickt wurde, verarbeitet das Backend die Formulardaten und sendet die Formulardaten per E-Mail oder speichert sie in einer Datenbank.

<?php

// Abrufen der Formulardaten
$formData = $_POST;

// Validierung der Formulardaten
if (!validateFormData($formData)) {
// Wenn die Formulardaten nicht gültig sind, wird eine Fehlermeldung angezeigt
echo 'Ihre Formulardaten sind nicht gültig.';
exit;
}

// Wenn alles korrekt ist, kann das E-Mail versendet werden
mail('info@example.com', 'Nachricht des Kontakt-Formulars', 'Hallo Webmaster, hier ist eine Nachricht des Kontaktformulars .........');

Hinzufügen von mosparo zum Prozess

Mit mosparo müssen Sie nun Ihren Backend-Prozess anpassen, um die Einsendung mit mosparo zu verifizieren.

<?php

// Abrufen der Formulardaten
$formData = $_POST;

// Überprüfen der Formulardaten mit mosparo
if (!verifyFormDataWithMosparo($formData)) {
// Allgemeine Fehlermeldung, wir kennen den genauen Grund für die fehlgeschlagene Überprüfung hier nicht
echo 'Die Formulardaten enthalten Spam.';
exit;
}

// Validierung der Formulardaten
if (!validateFormData($formData)) {
// Wenn die Formulardaten nicht gültig sind, wird eine Fehlermeldung angezeigt
echo 'Ihre Formulardaten sind nicht gültig.';
exit;
}

// Wenn alles korrekt ist, kann das E-Mail versendet werden
mail('info@example.com', 'Nachricht des Kontakt-Formulars', 'Hallo Webmaster, hier ist eine Nachricht des Kontaktformulars .........');

Die Verifizierung erfolgt in elf Schritten:

<?php

function verifyFormDataWithMosparo(array $formData)
{
// 1. Entfernen der ignorierten Felder aus den Formulardaten
// 2. Extrahieren des Einsende- und Validierungs-Codes aus den Formulardaten
// 3. Vorbereiten der Formulardaten
// 4. Erzeugen der Hashes
// 5. Generieren der Signatur der Formulardaten
// 6. Erzeugen der Validierungssignatur
// 7. Vorbereiten der Verifizierungssignatur
// 8. Sammeln der Anfragedaten
// 9. Generierung der Anfragesignatur
// 10. Senden der API-Anfrage
// 11. Prüfen der Antwort
}
1. Entfernen der ignorierten Felder aus den Formulardaten

mosparo validiert keine Feldtypen wie Checkbox, Radio, Password und Hidden. Es gibt noch weitere ignorierte Felder, die Sie in dieser Liste hier finden können: Ignorierte Felder

Sie müssen diese aus den Formulardaten entfernen, da mosparo diese Felder nicht validiert hat (siehe Vorbereiten der Formulardaten).

2. Extrahieren des Einsende- und Validierungs-Codes aus den Formulardaten

mosparo fügt automatisch den Einsende- und den Validierungs-Code zu Ihren Formulardaten hinzu. Sie sollten also diese beiden Werte in Ihren Formulardaten haben. Extrahieren Sie die beiden Werte und speichern Sie sie in einer Variablen:

$submitToken = $formData['_mosparo_submitToken'];
$validationToken = $formData['_mosparo_validationToken'];
3. Vorbereiten der Formulardaten

Nun müssen wir die Formulardaten bereinigen. Dazu müssen wir über die Formulardaten iterieren. Wenn der Feldname mit _mosparo_ beginnt, müssen wir dieses Feld aus den Formulardaten entfernen. Ausserdem müssen wir bei allen anderen Feldern CRLF-Zeilenumbrüche durch LF-Zeilenumbrüche ersetzen.

$preparedFormData = [];
foreach ($formData as $fieldName => $value) {
if (str_starts_with($fieldName, '_mosparo_')) {
continue;
}

$preparedFormData[$fieldName] = str_replace("\r\n", "\n", $value);
}
4. Erzeugen der Hashes

Da wir die Formulardaten nicht im Klartext an mosparo übertragen wollen, erstellen wir Hashes. Dazu iterieren wir über das Array der aufbereiteten Formulardaten und erstellen für jeden Wert einen SHA256-Hash. Bitte sortieren Sie das Array alphabetisch nach dem Feldnamen in aufsteigender Reihenfolge (A-Z).

foreach ($preparedFormData as $fieldName => $value) {
$preparedFormData[$fieldName] = hash('sha256', $value);
}

ksort($preparedFormData);
5. Generieren der Signatur der Formulardaten

Nun erstellen wir eine Signatur, um die Gültigkeit der vorbereiteten Formulardaten zu beweisen. Dazu konvertieren wir die vorbereiteten Formulardaten in einen JSON-String und erstellen dann einen HMAC SHA256-Hash mit dem geheimen Schlüssel des Projekts.

$jsonPreparedFormData = json_encode($preparedFormData);
$projectPrivateKey = '<privateKey>'; // Sie finden diesen Wert in den Projekteinstellungen in mosparo
$formDataSignature = hash_hmac('sha256', $jsonPreparedFormData, $projectPrivateKey);
6. Erzeugen der Validierungssignatur

Mit der gleichen Methode wie in Schritt 5 erstellen wir die Signatur des Validierungs-Codes (ein HMAC SHA256 Hash):

$validationSignature = hash_hmac('sha256', $validationToken, $projectPrivateKey);
7. Vorbereiten der Verifizierungssignatur

Um später die Antwort von mosparo zu bestätigen, erstellen wir eine Verifizierungssignatur. Die Signatur ist die Kombination aus der Validierungsignatur und der Signatur der Formulardaten als HMAC SHA256 Hash.

$combinedSignatures = $validationSignature . $formDataSignature;
$verificationSignature = hash_hmac('sha256', $combinedSignatures, $projectPrivateKey);
8. Sammeln der Anfragedaten

Nachdem wir die Formulardaten vorbereitet und die Signaturen erstellt haben, können wir nun die API-Anfrage für die Verifizierungs-API vorbereiten. Dazu bereiten wir die Anfragedaten vor, die wir benötigen, um die Verifizierungs-API zu kontaktieren:

$apiEndpoint = '/api/v1/verification/verify'; // Dies ist die API von mosparo, also ein fester Wert
$requestData = [
'submitToken' => $submitToken,
'validationSignature' => $validationSignature,
'formSignature' => $formDataSignature,
'formData' => $preparedFormData,
];
9. Generierung der Anfragesignatur

Um die Anfrage zu authentifizieren, benötigen wir eine Anfragesignatur. Wir erstellen einen weiteren HMAC SHA256-Hash mit der Kombination aus dem API-Endpunkt und den Anfragedaten als JSON-String als Wert.

$jsonRequestData = json_encode($requestData);
$combinedApiEndpointJsonRequestData = $apiEndpoint . $jsonRequestData;
$requestSignature = hash_hmac('sha256', $combinedApiEndpointJsonRequestData, $projectPrivateKey);
10. Senden der API-Anfrage

Wir haben alle notwendigen Werte vorbereitet und können die mosparo API kontaktieren. Dazu benötigen wir einen HTTP-Client, der die Anfrage an die API stellt. In diesem Beispiel verwenden wir die PHP-Bibliothek Guzzle, um die Anfrage zu stellen, aber Sie können natürlich auch jeden anderen Client verwenden. Die Anfrage an die API ist eine POST-Anfrage, und Sie müssen den öffentlichen Schlüssel und die Anfragesignatur in den Authorization-Header einfügen (als Basic-Authorization-Header, kodiert als Base64-String). Die Anfragedaten müssen als Post-Datenfelder der Anfrage gesendet werden.

$projectPublicKey = '<publicKey>'; // Sie finden diesen Wert in den Projekteinstellungen in mosparo
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://mosparo.example.com', // Der Host Ihrer mosparo-Installation
]);
$response = $client->request(
'POST',
$apiEndpoint,
[
'auth' => [$projectPublicKey, $requestSignature],
'form_params' => $requestData,
]
);
11. Prüfen der Antwort

Die Anfrage wurde abgeschickt, und wir haben eine Antwort erhalten. Jetzt ist es an der Zeit, das Ergebnis der Überprüfung zu überprüfen. Dekodieren Sie dazu den von der API zurückgegebenen JSON-String. Wenn die Verifizierung korrekt verarbeitet wurde (ohne HTTP-Fehlermeldungen), dann sollten Sie in der Antwort von mosparo die folgenden Felder finden: valid, verificationSignature, verifiedFields, und issues.

Wenn das Feld valid auf true gesetzt ist und das Feld verificationSignature den gleichen Wert enthält wie die vorbereitete Verifizierungssignatur in Schritt 7, dann sind die Formulardaten gültig, und Sie können die Daten verarbeiten. Wenn valid nicht true ist oder die Verifizierungssignatur nicht die gleiche ist, dann war etwas mit der Anfrage nicht in Ordnung (oder der Benutzer hat versucht, sie zu manipulieren), und sie wird daher als Spam eingestuft.

Es gibt noch einen weiteren entscheidenden Schritt. mosparo kann nur überprüfen, was es im Frontend erhalten hat und was Sie im Backend gesendet haben. Der Benutzer könnte ein Pflichtfeld im Browser in ein für mosparo ignoriertes Feld ändern und mosparo damit umgehen. Nach erfolgreicher Verifizierung sollten Sie sicherstellen, dass alle Ihre Pflichtfelder verifiziert sind. Dazu gibt mosparo das Array mit den verifizierten Feldern zurück. Stellen Sie sicher, dass alle Ihre Felder dort eingetragen sind:

$responseData = json_decode((string) $response->getBody(), true);

if (isset($responseData['valid']) && $responseData['valid'] && isset($responseData['verificationSignature']) && $responseData['verificationSignature'] == $verificationSignature) {
// Stellen Sie sicher, dass alle erforderlichen Felder von mosparo überprüft wurden.
if (!isset($responseData['verifiedFields']['name']) || !isset($responseData['verifiedFields']['emailAddress']) || !isset($responseData['verifiedFields']['message'])) {
return false;
}
return true;
}

return false;

Mehr dazu finden Sie hier: Umgehungsschutz

Komplette Funktion

Die vollständige Funktion zur Durchführung der Überprüfung sieht nun wie folgt aus:

<?php

function verifyFormDataWithMosparo(array $formData)
{
// 1. Entfernen der ignorierten Felder aus den Formulardaten
// Sie müssen dies nur tun, wenn Sie ignorierte Felder in Ihrem Formular haben

// 2. Extrahieren des Einsende- und Validierungs-Codes aus den Formulardaten
$submitToken = $formData['_mosparo_submitToken'];
$validationToken = $formData['_mosparo_validationToken'];

// 3. Vorbereiten der Formulardaten
$preparedFormData = [];
foreach ($formData as $fieldName => $value) {
if (str_starts_with($fieldName, '_mosparo_')) {
continue;
}

$preparedFormData[$fieldName] = str_replace("\r\n", "\n", $value);
}

// 4. Erzeugen der Hashes
foreach ($preparedFormData as $fieldName => $value) {
$preparedFormData[$fieldName] = hash('sha256', $value);
}

ksort($preparedFormData);

// 5. Generieren der Signatur der Formulardaten
$jsonPreparedFormData = json_encode($preparedFormData);
$projectPrivateKey = '<privateKey>'; // Sie finden diesen Wert in den Projekteinstellungen in mosparo
$formDataSignature = hash_hmac('sha256', $jsonPreparedFormData, $projectPrivateKey);

// 6. Erzeugen der Validierungssignatur
$validationSignature = hash_hmac('sha256', $validationToken, $projectPrivateKey);

// 7. Vorbereiten der Verifizierungssignatur
$combinedSignatures = $validationSignature . $formDataSignature;
$verificationSignature = hash_hmac('sha256', $combinedSignatures, $projectPrivateKey);

// 8. Sammeln der Anfragedaten
$apiEndpoint = '/api/v1/verification/verify'; // Dies ist die API von mosparo, also ein fester Wert
$requestData = [
'submitToken' => $submitToken,
'validationSignature' => $validationSignature,
'formSignature' => $formDataSignature,
'formData' => $preparedFormData,
];

// 9. Generierung der Anfragesignatur
$jsonRequestData = json_encode($requestData);
$combinedApiEndpointJsonRequestData = $apiEndpoint . $jsonRequestData;
$requestSignature = hash_hmac('sha256', $combinedApiEndpointJsonRequestData, $projectPrivateKey);

// 10. Senden der API-Anfrage
$projectPublicKey = '<publicKey>'; // Sie finden diesen Wert in den Projekteinstellungen in mosparo
$client = new \GuzzleHttp\Client([
'base_uri' => 'https://mosparo.example.com', // Der Host Ihrer mosparo-Installation
]);
$response = $client->request(
'POST',
$apiEndpoint,
[
'auth' => [$projectPublicKey, $requestSignature],
'form_params' => $requestData,
]
);

// 11. Prüfen der Antwort
$responseData = json_decode((string) $response->getBody(), true);

if (isset($responseData['valid']) && $responseData['valid'] && isset($responseData['verificationSignature']) && $responseData['verificationSignature'] == $verificationSignature) {
// Stellen Sie sicher, dass alle erforderlichen Felder von mosparo überprüft wurden.
if (!isset($responseData['verifiedFields']['name']) || !isset($responseData['verifiedFields']['emailAddress']) || !isset($responseData['verifiedFields']['message'])) {
return false;
}
return true;
}

return false;
}

Nach der Verifizierung

Wenn die Überprüfung erfolgreich war, können Sie die Formulardaten nun wie bisher weiterverarbeiten, z. B. per E-Mail versenden oder in einer Datenbank speichern.

Felder in der API-Antwort

Die Antwort der API von mosparo gibt an, ob eine Antwort korrekt ist oder ob eine Anfrage ungültig ist. Die folgenden Felder können in der Anfrage enthalten sein:

FeldTypBeschreibung
validBooleanGibt an, ob eine Anfrage gültig (also abgesendet werden darf) oder ungültig (manipuliert) ist.
verificationSignatureStringmosparo berechnet die eigene Verifikationssignatur, welche mit der vor dem Absenden der Anfrage berechneten Verifikationssignatur übereinstimmen muss.
issuesArrayEin Array mit allen Problemen, welche bei der ÜBerprüfung festgestellt wurden.
verifiedFieldsObjektGibt an, welche Felder der Formulardaten überprüft wurden und was der Zustand der jeweiligen Felder ist.
errorBooleanWenn ein Fehler aufgetreten ist, ist dieses Feld auf true gesetzt.
errorMessageStringDie Fehlermeldung des Fehlers.

Falls bei der Überprüfung ein Fehler aufgetreten ist, wird das Feld error sowie errorMessage gesetzt. Die beiden Felder geben an das ein Fehler aufgetreten ist und was die Fehlermeldung dazu ist. Dies passiert beispielsweise, wenn der öffentliche Schlüssel oder eine der Signaturen ungültig waren oder ein anderes Problem auftrat.

Werte für verifiedFields
WertBeschreibung
validDas Feld wurde korrekt überprüft und ist gültig.
invalidDas Feld wurde nicht korrekt validiert, sprich der Wert, welcher bei der Verifizierung übermittelt wurde, stimmt nicht mit dem Wert überein, welcher im Formular ursprünglich eingetragen wurde.