Qu'est-ce qu'un formulaire de don ?
Les formulaires de don sont une infrastructure qui vous permet de collecter des dons en les intégrant à votre propre site web. Vous pouvez créer un formulaire de don en accédant à la section Dons > Formulaire de Don dans le menu de gauche.
Qu'est-ce qui a changé par rapport à la V1 ?
Les formulaires de don peuvent désormais fonctionner à la fois intégrés à votre site et en tant que pop-up.
Il n'est pas nécessaire d'envoyer un paramètre pour le montant, le don récurrent, la devise, etc.
La structure de notification de résultat (Callback) a été convertie de JS à HTTP POST.
Le test a été simplifié.
L'adresse du site web doit être saisie en tant qu'adresse complète.
La possibilité d'offrir des options de montant prédéfinies a été ajoutée.
Des messages d'erreur ont été ajoutés dans la console du développeur.
À quoi faut-il faire attention lors de la création ?
Le point le plus important à prendre en compte lors de la création d'un formulaire de don est de saisir l'adresse complète du site web sur lequel vous utiliserez le formulaire. Lors de la saisie de l'adresse, vous devez inclure https:// au début. Et si votre site web a plusieurs versions, vous devez le rendre unique.
Les formulaires de don ne fonctionnent qu'avec HTTPS en environnement de production. Vous pouvez les tester avec HTTP en environnement de test.
Par exemple ;
https://www.alanadi.org/bagis/genel-bagis
Si votre site fonctionne à la fois sous https://www.alanadi.org et https://alanadi.org, veuillez n'en choisir qu'un et rediriger le nom de domaine non choisi vers l'autre.
Intégration au site web
ATTENTION ! Cette intégration nécessite des connaissances en développement logiciel. Vous devez maîtriser les bases du HTML et du Javascript. Si vous n'êtes pas familier avec ces sujets, veuillez utiliser nos pages de don standard.
Tout d'abord, jQuery doit absolument être chargé sur votre site web. Si jQuery n'est pas chargé, Fonzip générera une erreur.
Deuxièmement, si la valeur de l'en-tête Referrer-Policy de votre page est no-referrer, Fonzip générera une erreur. Vous devez utiliser une valeur différente de celle-ci.
Vous pouvez accéder aux informations d'intégration de base depuis la section Dons > Formulaires de Don > Actions > Informations d'Intégration.
<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>Ajoutez notre script à la page comme suit.
Si vous souhaitez exécuter le formulaire en tant qu'intégré, à l'intérieur du bloc <script>
fzv2("embed", "KEY", "ID-À-AJOUTER");Si vous souhaitez l'exécuter en tant que popup, à l'intérieur du bloc <script>
fzv2("popup", "KEY", "ID-DU-BOUTON");Vous devez ajouter le code.
Si vous souhaitez lancer le formulaire intégré, mais qu'il reste masqué :
fzv2("embed", "KEY", "ID-À-AJOUTER", true);
Il suffit d'envoyer le 4ème paramètre comme true.
La balise HTML à laquelle le formulaire intégré sera ajouté doit être <body>, <div> ou <section>.
La balise HTML qui déclenchera le formulaire pop-up doit être <button> ou <a>.
Les formulaires de don fonctionnent automatiquement dans la langue du navigateur. Si le paramètre lang est défini dans le bloc html de votre page web, il prendra cette langue en compte. Si vous souhaitez forcer une langue spécifique, avant les fonctions d'intégration et de popup ;
fzv2("lang", "LANGUE")Vous pouvez effectuer la sélection de la langue comme suit.
Langues valides
tr (Turc)
en (Anglais)
de (Allemand)
fr (Français)
es (Espagnol)
it (Italien)
pt (Portugais)
nl (Néerlandais)
ru (Russe)
Transfert de données vers le formulaire
Si vous souhaitez ajouter une valeur prédéfinie à un formulaire pop-up, vous pouvez ajouter les attributs suivants au bouton correspondant. Ou vous pouvez transférer des données à n'importe quel formulaire à tout moment en utilisant la fonction "data". Vous pouvez utiliser la fonction "data" en supprimant l'attribut "fz-data". Par exemple ;
fzv2("data", "embed", "KEY", "currency", "USD")Paramètres | Description | Valeur |
fz-data-currency | Devise | ISO 4217 |
fz-data-recurring | Récurrent / Ponctuel | true|false |
fz-data-amount | Montant du don | Numérique |
fz-data-recurring-limit | Don récurrent limité dans le temps | 0 - 60 |
fz-data-donor-type | Type de donateur | corporate|personal |
fz-data-first-name | Prénom / Nom d'entreprise | Alphanumérique{0,200} |
fz-data-last-name | Nom de famille | Alphanumérique{0,200} |
fz-data-email | Email{0,200} | |
fz-data-phone | Téléphone | Téléphone{0,25} |
fz-data-birthday | Date de naissance | Date (Jour/Mois/Année) |
fz-data-city | Ville | Alphanumérique{0,200} |
fz-data-district | District | Alphanumérique{0,200} |
fz-data-address | Adresse | Alphanumérique |
fz-data-tckno | Numéro d'identité TR / Numéro fiscal | Numérique{11,13} |
fz-data-details | Détails | Alphanumérique{0,300} |
fz-data-referring | Au nom de quelqu'un | true|false |
fz-data-referring-name | Personne au nom de laquelle le don est fait | Alphanumérique{0,100} |
fz-data-referring-email | E-mail de la personne au nom de laquelle le don est fait | Email{0,100} |
fz-data-news-via-phone | Autorisation de communication par téléphone | true|false |
fz-data-news-via-sms | Autorisation de communication par SMS | true|false |
fz-data-news-via-email | Autorisation de communication par e-mail | true|false |
fz-data-fundraising-campaign-id | Campagne de don | Numérique |
fz-data-name-hidden | Nom masqué | true|false |
fz-data-amount-visible | Montant du don visible | true|false |
fz-data-api-tracking-id | ID de suivi API | Alphanumérique{0,20} |
fz-data-custom-parameters | Paramètres personnalisés |
|
Si les attributs ajoutés remplissent tout le formulaire, le formulaire passe automatiquement aux étapes suivantes. C'est-à-dire que si les informations de montant sont présentes, il est automatiquement dirigé vers la section des informations du donateur, et si les informations du donateur sont également présentes, il est directement dirigé vers la section des informations de la carte.
Paramètres personnalisés
Vous pouvez utiliser la fonction de paramètres personnalisés pour transférer à Fonzip n'importe quel champ que vous utilisez lors de la collecte de dons, mais qui n'est pas défini dans Fonzip.
Création de paramètres personnalisés
Vous pouvez créer un paramètre en cliquant sur Ajouter un paramètre dans la section Paramètres personnalisés, située en bas de la page de création/modification du formulaire de don.
Dans l'écran qui apparaît, saisissez la valeur de la clé que vous souhaitez passer dans le paramètre dans la section Nom du champ, et la valeur que vous souhaitez voir apparaître dans le système dans la section Description, puis enregistrez.
Par exemple, nous avons créé un paramètre nommé reçu pour le nom du champ et Demande de reçu pour la description. Si la personne qui fait le don souhaite un reçu supplémentaire, nous remplirons ce champ avec "Oui", et si elle ne le souhaite pas, avec "Non".
Remarque : Il n'y a aucune restriction sur les valeurs à passer dans les paramètres.
Vous devez passer une chaîne JSON à l'attribut fz-data-custom-parameters. Exemple
<button id="fonzip-button" fz-data-custom-parameters="{'makbuz': 'makbuz_degeri'}"/>Une fois le don effectué, si l'option de demande de reçu a été sélectionnée, vous pouvez voir les données correspondantes dans les détails du don, comme ci-dessous.
Avertissements concernant les paramètres personnalisés
L'envoi d'un paramètre non défini dans les paramètres du formulaire entraînera une erreur système.
L'envoi de données dans un format autre que JSON entraînera une erreur système.
Si vous modifiez/supprimez le nom d'un paramètre que vous avez ajouté précédemment, vous risquez de perdre les données des dons associés.
Politique de sécurité du contenu
Si vous protégez votre site avec une CSP à des fins de sécurité, vous devez ajouter les définitions suivantes.
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
Si vous utilisez un Nonce, la valeur du Nonce avant les fonctions embed ou popup
fzv2("nonce", "VALEUR-NONCE");Vous pouvez le définir comme suit.
Notifications de retour de résultat
Si vous ne définissez pas d'URL de retour de résultat lors de la création/modification de votre formulaire, Fonzip affichera l'écran de résultat standard (succès/échec), puis redirigera le donateur vers l'Adresse de la page que vous avez définie.
Si vous l'avez défini, le résultat de l'opération sera envoyé en tant que HTTP POST à l'URL que vous avez spécifiée. Vous pouvez trouver les paramètres à envoyer dans le tableau ci-dessous.
Si l'URL que vous avez définie est protégée contre les requêtes POST par une protection CSRF, cette protection doit être désactivée. Alternativement, vous pouvez effectuer une vérification sur le paramètre hash pour confirmer que la requête provient de Fonzip. Cette vérification est fortement recommandée.
Calcul du paramètre de hachage
Pour le calcul du paramètre hash, le conversation_id et la Secret Key sont hachés avec l'algorithme sha256 et convertis en base 16.
hash = sha256(conversation_id + Secret Key)
Exemple :
conversation_id = 123456
Secret Key = gizlianahtar
hash = sha256(12345gizlianahtar) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6
Paramètre | Description |
donation_id | N° d'enregistrement |
donor_type | Type de donateur |
name | Nom et prénom du donateur |
first_name | Prénom / Nom d'entreprise |
last_name | Nom de famille |
phone | Téléphone |
birthday | Date de naissance |
city | Ville |
district | District |
address | Adresse |
details | Détails |
tckno | Numéro d'identité TR / Numéro fiscal |
referring | Au nom de quelqu'un |
referring_name | Personne au nom de laquelle le don est fait |
referring_email | E-mail de la personne au nom de laquelle le don est fait |
recurring | Récurrent / Ponctuel |
recurring_limit | Don récurrent limité dans le temps |
recurring_order_id | N° d'instruction de don récurrent |
category_id | ID de catégorie de don |
category | Catégorie de don |
name_hidden | Nom masqué |
amount_visible | Montant du don visible |
custom_parameters | Paramètres personnalisés |
donation_form_id | ID du formulaire de don |
donation_form | Formulaire de don |
news_via_phone | Autorisation de communication par téléphone |
news_via_sms | Autorisation de communication par SMS |
news_via_email | Autorisation de communication par e-mail |
lang | Langue |
complete_date | Date de transaction (ISO 8601) |
amount | Montant du don |
currency | Devise (ISO 4217) |
ip_address | Adresse IP |
payment_status | Statut du paiement
3: Réussi
5: Échoué |
payment_method | Méthode de paiement
0: Carte
8: BKM Express
9: iDEAL
10: Payer avec Iyzico |
payment_settings_id | ID POS virtuel |
api_tracking_id | ID de suivi API |
order_id | N° de commande bancaire |
conversation_id | ID de trace |
last_four | Quatre derniers chiffres de la carte |
bin_number | Numéro BIN de la carte |
transaction_id | N° de transaction bancaire |
provision_no | N° d'autorisation bancaire |
auth_code | Numéro d'approbation |
reference_id | Numéro de référence |
error_code | Code d'erreur |
error_text | Message d'erreur |
hash | Hash |
Paramètres avancés
Si vous souhaitez supprimer un formulaire de votre page, vous devez utiliser la fonction "destroy".
fzv2("destroy", "popup", "KEY")
fzv2("destroy", "embed", "KEY")
Si vous souhaitez afficher un formulaire masqué, vous pouvez utiliser la fonction "show".
fzv2("show", "popup", "KEY")
fzv2("show", "embed", "KEY")
Si vous souhaitez masquer un formulaire affiché, vous pouvez utiliser la fonction "hide".
fzv2("hide", "popup", "KEY")
fzv2("hide", "embed", "KEY")
Si vous souhaitez recevoir un retour d'information lorsqu'un formulaire pop-up est fermé, vous devez définir la fonction que vous souhaitez appeler avec la fonction "callback".
function close_function(KEY) {
console.log("popup closed", KEY)
}
fzv2("callback", "popup", "KEY", "close", close_function)
Migration de la V1 vers la V2
Tout d'abord, créez un formulaire de don pour la V2. Comme il fonctionnera comme un pop-up comme auparavant, sur votre page
fzv2("popup", "KEY", "ID-DU-BOUTON");Vous devez le lancer comme suit.
Vous pouvez refléter les événements de changement de montant, de récurrence et de devise sur les attributs commençant par fz-data-*, avant de lancer les opérations effectuées avec fz.bagis() sans envoyer les paramètres de montant, de récurrence, de devise dans le popup de la V1.
Par exemple, auparavant
<script>
function bagis_yap() {
var miktar = document.getElementById("miktar").value;
var duzenli = document.getElementById("duzenli").checked;
fz.bagis({
amount: miktar,
recurring: duzenli
//Autres paramètres
})
}
</script>
<input id="miktar" type="number" step="0.01" placeholder="Montant du don"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Faire un don récurrent</label>
<a onclick="bagis_yap();" href="javascript:;>Faire un don</a>
au lieu de récupérer des valeurs comme celles-ci et d'appeler fz.bagis() lorsque le bouton est cliqué, vous devez refléter les valeurs correspondantes sur les attributs fz-data-* pertinents lorsque ces valeurs changent. Par exemple
<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="Montant du don"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Faire un don récurrent</label>
<a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Faire un don</a>