Was ist ein Spendenformular?
Spendenformulare sind eine Infrastruktur, die es Ihnen ermöglicht, Spenden zu erhalten, indem Sie sie in Ihre eigene Website integrieren. Sie können ein Spendenformular erstellen, indem Sie zum Menüpunkt Spenden > Spendenformular auf der linken Seite gehen.
Was hat sich im Vergleich zu V1 geändert?
Spendenformulare können jetzt sowohl eingebettet als auch als Popup auf Ihrer Website verwendet werden.
Es ist nicht mehr nötig, Parameter wie Betrag, wiederkehrende Spende, Währung usw. zu senden.
Die Rückrufstruktur (Callback) wurde von JS auf HTTP POST umgestellt.
Das Testen wurde vereinfacht.
Die Website-Adresse muss als vollständige Adresse eingegeben werden.
Es wurde die Möglichkeit hinzugefügt, vordefinierte Betragsoptionen anzubieten.
Fehlermeldungen wurden in der Entwicklerkonsole hinzugefügt.
Worauf sollte man bei der Erstellung achten?
Der wichtigste Punkt beim Erstellen eines Spendenformulars ist, dass Sie die vollständige Adresse der Website eingeben müssen, auf der Sie das Formular verwenden werden. Geben Sie die Adresse mit https:// am Anfang ein. Wenn Ihre Website mehrere Versionen hat, sollten Sie sie auf eine einzige Version beschränken.
Spendenformulare funktionieren in der Live-Umgebung nur mit HTTPS. In der Testumgebung können Sie sie mit HTTP testen.
Zum Beispiel;
https://www.domainname.org/spende/allgemeine-spende
Wenn Ihre Website sowohl unter https://www.domainname.org als auch unter https://domainname.org erreichbar ist, wählen Sie bitte nur eine davon aus und leiten Sie die nicht gewählte Domain auf die andere um.
Website-Integration
WARNUNG! Diese Integration erfordert Softwarekenntnisse. Sie müssen über grundlegende Kenntnisse in HTML und Javascript verfügen. Wenn Sie diese Kenntnisse nicht haben, verwenden Sie bitte unsere Standard-Spendenseiten.
Zuerst muss jQuery auf Ihrer Website geladen sein. Wenn jQuery nicht geladen ist, gibt Fonzip einen Fehler aus.
Zweitens, wenn der Referrer-Policy-Header-Wert auf Ihrer Seite no-referrer ist, gibt Fonzip einen Fehler aus. Sie müssen einen anderen Wert als diesen verwenden.
Sie können die grundlegenden Integrationsinformationen im Bereich Spenden > Spendenformulare > Aktionen > Integrationsinformationen abrufen.
<script type="text/javascript"> !function(e,t,s,n,c){e.fzv2||(n=e.fzv2=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)},e._fzv2||(e._fzv2=n),(n.push=n).loaded=!0,n.version="1.0",n.queue=[],fzv2.script_element=t.createElement(s),fzv2.script_element.async=!0,fzv2.script_element.src="https://s.fonzip.com/js/fzembed.v1.js",(c=t.getElementsByTagName(s)[0]).parentNode.insertBefore(fzv2.script_element,c))}(window,document,"script"); </script>Fügen Sie unser Skript wie folgt auf der Seite hinzu.
Wenn Sie das entsprechende Formular eingebettet ausführen möchten, fügen Sie Folgendes in den <script>-Block ein:
fzv2("embed", "KEY", "ID-ZUM-HINZUFÜGEN");Wenn Sie es als Popup ausführen möchten, fügen Sie Folgendes in den <script>-Block ein:
fzv2("popup", "KEY", "BUTTON-ID");Sie müssen den Code hinzufügen.
Wenn Sie das eingebettete Formular starten, es aber ausgeblendet bleiben soll:
fzv2("embed", "KEY", "ID-ZUM-HINZUFÜGEN", true);Es genügt, den 4. Parameter als true zu senden.
Das HTML-Tag, in das das eingebettete Formular eingefügt wird, muss <body>, <div> oder <section> sein.
Das HTML-Tag, das das Popup-Formular auslöst, muss <button> oder <a> sein.
Spendenformulare funktionieren automatisch in der Sprache des Browsers. Wenn der lang-Parameter im html-Block Ihrer Webseite definiert ist, wird diese Sprache berücksichtigt. Wenn Sie eine bestimmte Sprache erzwingen möchten, fügen Sie vor den Embed- und Popup-Funktionen Folgendes ein:
fzv2("lang", "SPRACHE")Sie können die Sprache wie folgt auswählen.
Gültige Sprachen
tr (Türkisch)
en (Englisch)
de (Deutsch)
fr (Französisch)
es (Spanisch)
it (Italienisch)
pt (Portugiesisch)
nl (Niederländisch)
ru (Russisch)
Datenübertragung an das Formular
Wenn Sie dem Popup-Formular einen vordefinierten Wert hinzufügen möchten, können Sie dem entsprechenden Button die folgenden Eigenschaften hinzufügen. Alternativ können Sie jederzeit Daten mit der Funktion "data" an jedes Formular übertragen. Sie können die "data"-Funktion verwenden, indem Sie das "fz-data"-Attribut entfernen. Zum Beispiel;
fzv2("data", "embed", "KEY", "currency", "USD")Eigenschaften | Beschreibung | Wert |
fz-data-currency | Währung | ISO 4217 |
fz-data-recurring | Wiederkehrend / Einmalig | true|false |
fz-data-amount | Spendenbetrag | Zahl |
fz-data-recurring-limit | Befristete wiederkehrende Spende | 0 - 60 |
fz-data-donor-type | Spendertyp | corporate|personal |
fz-data-first-name | Vorname / Firmenname | Alphanumerisch{0,200} |
fz-data-last-name | Nachname | Alphanumerisch{0,200} |
fz-data-email | E-Mail{0,200} | |
fz-data-phone | Telefon | Telefon{0,25} |
fz-data-birthday | Geburtsdatum | Datum (Tag/Monat/Jahr) |
fz-data-city | Stadt | Alphanumerisch{0,200} |
fz-data-district | Bezirk | Alphanumerisch{0,200} |
fz-data-address | Adresse | Alphanumerisch |
fz-data-tckno | TC-ID-Nummer / Steuernummer | Zahl{11,13} |
fz-data-details | Beschreibung | Alphanumerisch{0,300} |
fz-data-referring | Im Namen einer Person | true|false |
fz-data-referring-name | Person, in deren Namen gespendet wird | Alphanumerisch{0,100} |
fz-data-referring-email | E-Mail der Person, in deren Namen gespendet wird | E-Mail{0,100} |
fz-data-news-via-phone | Erlaubnis zur Kontaktaufnahme per Telefon | true|false |
fz-data-news-via-sms | Erlaubnis zur Kontaktaufnahme per SMS | true|false |
fz-data-news-via-email | Erlaubnis zur Kontaktaufnahme per E-Mail | true|false |
fz-data-fundraising-campaign-id | Spendenkampagne | Zahl |
fz-data-name-hidden | Name soll nicht angezeigt werden | true|false |
fz-data-amount-visible | Spendenbetrag soll angezeigt werden | true|false |
fz-data-api-tracking-id | API Tracking ID | Alphanumerisch{0,20} |
fz-data-custom-parameters | Benutzerdefinierte Parameter |
Wenn die hinzugefügten Eigenschaften das gesamte Formular ausfüllen, wechselt das Formular automatisch zu den nächsten Schritten. Das bedeutet, wenn Betragsinformationen vorhanden sind, wird es automatisch zum Abschnitt mit den Spenderinformationen weitergeleitet, und wenn Spenderinformationen vorhanden sind, wird es direkt zum Abschnitt mit den Karteninformationen weitergeleitet.
Benutzerdefinierte Parameter
Sie können die Funktion für benutzerdefinierte Parameter verwenden, um alle Felder, die nicht in Fonzip definiert sind, aber von Ihnen beim Empfangen von Spenden verwendet werden, an Fonzip zu übertragen.
Erstellung benutzerdefinierter Parameter
Sie können einen Parameter erstellen, indem Sie auf der Seite zum Erstellen/Bearbeiten des Spendenformulars im Abschnitt "Benutzerdefinierte Parameter" ganz unten auf Parameter hinzufügen klicken.
Geben Sie im angezeigten Bildschirm im Feld Feldname den Schlüsselwert ein, den Sie im Parameter übergeben möchten, und im Feld Beschreibung den Wert, den Sie im System anzeigen lassen möchten, und speichern Sie ihn.
Zum Beispiel haben wir einen Parameter mit dem Feldnamen receipt und der Beschreibung Beleg anfordern erstellt. Wenn der Spender zusätzlich einen Beleg wünscht, füllen wir dieses Feld mit "Ja" aus, wenn er keinen Beleg wünscht, mit "Nein".
Hinweis: Es gibt keine Einschränkungen bei den Werten, die in den Parametern übergeben werden.
Sie müssen einen JSON-String an die Eigenschaft fz-data-custom-parameters übergeben. Beispiel
<button id="fonzip-button" fz-data-custom-parameters="{'makbuz': 'makbuz_degeri'}"/>Nach Abschluss der Spende, wenn die Option "Beleg anfordern" ausgewählt wurde, können Sie die entsprechenden Daten in den Spendendetails wie folgt sehen.
Warnungen zu benutzerdefinierten Parametern
Das Senden eines Parameters, der nicht in den Formulareinstellungen definiert ist, führt zu einem Systemfehler.
Das Senden von Daten, die nicht im JSON-Format vorliegen, führt zu einem Systemfehler.
Wenn Sie den Feldnamen eines zuvor hinzugefügten Parameters später ändern/löschen, können Sie die Daten in den entsprechenden Spenden verlieren.
Content Security Policy
Wenn Sie Ihre Website aus Sicherheitsgründen mit CSP schützen, müssen Sie die folgenden Definitionen hinzufügen.
script-src: https://s.fonzip.com
connect-src: https://fonzip.com
style-src: https://s.fonzip.com
img-src: https://s.fonzip.com https://cdn.fonzip.com
frame-src: https://fonzip.com
Wenn Sie Nonce verwenden, definieren Sie den Nonce-Wert vor den Embed- oder Popup-Funktionen wie folgt:
fzv2("nonce", "NONCE-VALUE");Sie können es wie folgt definieren.
Ergebnis-Rückmeldungen
Wenn Sie beim Erstellen/Bearbeiten Ihres Formulars keine Ergebnis-Rückgabe-URL definieren, zeigt Fonzip den Standard-Erfolgs-/Fehlerbildschirm an und leitet den Spender dann zu der von Ihnen definierten Seitenadresse weiter.
Wenn Sie eine URL definiert haben, wird das Ergebnis der Transaktion als HTTP POST an die von Ihnen definierte URL gesendet. Die zu sendenden Parameter finden Sie in der folgenden Tabelle.
Wenn die von Ihnen definierte URL über einen CSRF-Schutz für POST-Anfragen verfügt, muss dieser Schutz entfernt werden. Alternativ können Sie den hash-Parameter verwenden, um zu überprüfen, ob die Anfrage von Fonzip stammt. Es wird dringend empfohlen, diese Überprüfung durchzuführen.
Berechnung des Hash-Parameters
Zur Berechnung des hash-Parameters werden conversation_id und Secret Key mit dem sha256-Algorithmus gehasht und in das hexadezimale System umgewandelt.
hash = sha256(conversation_id + Secret Key)
Beispiel:
conversation_id = 123456
Secret Key = geheimeSchlüssel
hash = sha256(12345geheimeSchlüssel) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6
Parameter | Beschreibung |
donation_id | Registrierungs-Nr. |
donor_type | Spendertyp |
name | Name des Spenders |
first_name | Vorname / Firmenname |
last_name | Nachname |
phone | Telefon |
birthday | Geburtsdatum |
city | Stadt |
district | Bezirk |
address | Adresse |
details | Beschreibung |
tckno | TC-ID-Nummer / Steuernummer |
referring | Im Namen einer Person |
referring_name | Person, in deren Namen gespendet wird |
referring_email | E-Mail der Person, in deren Namen gespendet wird |
recurring | Wiederkehrend / Einmalig |
recurring_limit | Befristete wiederkehrende Spende |
recurring_order_id | Wiederkehrende Spendenauftrags-Nr. |
category_id | Spendenkategorie-ID |
category | Spendenkategorie |
name_hidden | Name soll nicht angezeigt werden |
amount_visible | Spendenbetrag soll angezeigt werden |
custom_parameters | Benutzerdefinierte Parameter |
donation_form_id | Spendenformular-ID |
donation_form | Spendenformular |
news_via_phone | Erlaubnis zur Kontaktaufnahme per Telefon |
news_via_sms | Erlaubnis zur Kontaktaufnahme per SMS |
news_via_email | Erlaubnis zur Kontaktaufnahme per E-Mail |
lang | Sprache |
complete_date | Transaktionsdatum (ISO 8601) |
amount | Spendenbetrag |
currency | Währung (ISO 4217) |
ip_address | IP-Adresse |
payment_status | Zahlungsstatus 3: Erfolgreich 5: Fehlgeschlagen |
payment_method | Zahlungsmethode 0: Karte 8: BKM Express 9: iDEAL 10: Bezahlen mit Iyzico |
payment_settings_id | Virtuelle POS-ID |
api_tracking_id | API Tracking ID |
order_id | Bank-Bestell-Nr. |
conversation_id | Trace ID |
last_four | Letzte 4 Ziffern der Karte |
bin_number | Karten-BIN-Nummer |
transaction_id | Bank-Transaktions-Nr. |
provision_no | Bank-Autorisierungs-Nr. |
auth_code | Autorisierungsnummer |
reference_id | Referenznummer |
error_code | Fehlercode |
error_text | Fehlermeldung |
hash | Hash |
Erweiterte Einstellungen
Wenn Sie ein Formular von Ihrer Seite entfernen möchten, müssen Sie die Funktion "destroy" verwenden.
fzv2("destroy", "popup", "KEY")
fzv2("destroy", "embed", "KEY")Wenn Sie ein ausgeblendetes Formular anzeigen möchten, können Sie die Funktion "show" verwenden.
fzv2("show", "popup", "KEY")
fzv2("show", "embed", "KEY")Wenn Sie ein angezeigtes Formular ausblenden möchten, können Sie die Funktion "hide" verwenden.
fzv2("hide", "popup", "KEY")
fzv2("hide", "embed", "KEY")Wenn Sie eine Rückmeldung erhalten möchten, wenn ein Popup-Formular geschlossen wird, müssen Sie die Funktion definieren, die mit der Funktion "callback" aufgerufen werden soll.
function close_function(KEY) {
console.log("popup closed", KEY)
}
fzv2("callback", "popup", "KEY", "close", close_function)Migration von V1 zu V2
Erstellen Sie zuerst ein Spendenformular für V2. Da es wie zuvor als Popup funktioniert, müssen Sie es auf Ihrer Seite wie folgt starten:
fzv2("popup", "KEY", "BUTTON-ID");Sie müssen es wie folgt starten.
Bevor Sie die im V1-Popup mit fz.bagis() durchgeführten Operationen starten, ohne Betrag, Wiederholung und Währungsparameter zu senden, können Sie die Ereignisse dieser Änderungen von Betrag, Wiederholung und Währung auf die Attribute, die mit fz-data-* beginnen, abbilden.
Zum Beispiel früher
<script>
function bagis_yap() {
var miktar = document.getElementById("miktar").value;
var duzenli = document.getElementById("duzenli").checked;
fz.bagis({
amount: miktar,
recurring: duzenli
//Di\u011fer parametreler
})
}
</script>
<input id="miktar" type="number" step="0.01" placeholder="Spendenbetrag"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Regelmäßig spenden</label>
<a onclick="bagis_yap();" href="javascript:;>Spenden</a>
Anstatt Werte wie diese zu übernehmen und bei Klick auf den Button fz.bagis() aufzurufen, müssen Sie die entsprechenden Werte auf die entsprechenden fz-data-*-Attribute abbilden, wenn sich die Werte ändern. Zum Beispiel
<script>
document.getElementById("miktar").addEventListener("change", function(event) {
this.setAttribute("fz-data-amount", this.value);
});
document.getElementById("duzenli").addEventListener("change", function(event) {
this.setAttribute("fz-data-recurring", this.checked);
})
</script>
<input id="miktar" type="number" step="0.01" placeholder="Spendenbetrag"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Regelmäßig spenden</label>
<a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Spenden</a>