Widget de formulaire

Le widget vérifie l'adresse pendant la saisie, propose la correction d'une faute de frappe, affiche un message et peut empêcher l'envoi du formulaire. Il s'installe avec une balise <script> et ne contient aucun secret : la page ne porte que l'identifiant public du widget.

N'exposez jamais une clé API dans une page web

N'appelez pas POST /v2/email/validate depuis le navigateur avec une clé : elle serait lisible par n'importe quel visiteur. Le widget est fait pour ce cas, avec ses protections : contrôle de l'origine, preuve de travail anti-robot, limites par IP et par appareil.

Installer

1. Dans le tableau de bord, ouvrez Widget JS et créez un widget.
2. Rattachez-lui une clé API et déclarez les domaines de votre site (monsite.fr, *.monsite.fr). Le widget ne répond que depuis ces domaines.
3. Réglez le champ ciblé, le déclenchement, les messages et l'apparence. L'aperçu se met à jour en direct.
4. Copiez le snippet et collez-le dans vos pages, idéalement juste avant </body>.

<!-- YesWeCheck — vérification email en temps réel -->
<script async src="https://api.yeswecheck.fr/widget/ywc-email-widget.js" data-ywc-widget="VOTRE_WIDGET_ID"></script>

C'est tout. Au chargement, le script lit data-ywc-widget, récupère sa configuration et s'attache aux champs ciblés (par défaut input[type="email"]). Une modification faite dans le tableau de bord s'applique au prochain chargement de page, sans toucher au snippet.

Ce que voit l'internaute

• Un état visuel sur le champ : en cours, valide, à vérifier, invalide.
• Un message adapté au cas : adresse jetable, compte générique, domaine accept-all, serveur non concluant…
• « Vouliez-vous dire [email protected] ? » sur une faute de frappe, avec correction en un clic.
• Des suggestions de domaine pendant la frappe après le @ (gmail.com, orange.fr…), adaptées au pays.

Réglages principaux

Réglage	Effet
Champ ciblé	Sélecteur CSS des champs à surveiller
Déclenchement	À la sortie du champ (défaut) ou pendant la frappe, avec délai d'attente
Messages	Textes de chaque état et de chaque cas
Apparence	Couleurs, icônes, thème ; chaque cas de verdict est rangé dans une catégorie avec son libellé et son action
Suggestions de domaine	Activées par défaut, pays détecté depuis le navigateur
Captcha (Altcha)	Preuve de travail résolue par le navigateur, invisible pour l'internaute ; pour chaque validation ou seulement quand le SMTP est en jeu
Protection anti-abus	Limites par IP, par appareil et par jour ; dégrader (validation sans SMTP) ou bloquer au-delà

Bloquer l'envoi du formulaire

Chaque catégorie de verdict a une action : laisser passer, avertir ou bloquer. Par défaut, tout passe. Quand une catégorie est réglée sur « bloquer », le widget empêche la soumission du formulaire tant que l'adresse saisie y reste.

Le blocage est volontairement permissif en cas de doute : il n'agit que sur un résultat obtenu pour la valeur actuellement saisie. Si l'API ne répond pas, le formulaire part.

Pour désactiver le blocage sur une page ou un formulaire précis sans toucher à la configuration, ajoutez l'attribut data-ywc-no-gating sur la balise <script>, sur le <form> ou sur le champ :

<form action="/inscription" method="post" data-ywc-no-gating>
  <input type="email" name="email" required />
</form>

Revalidez toujours côté serveur

Le widget améliore la saisie, il ne remplace pas un contrôle serveur : un robot peut envoyer votre formulaire sans exécuter le JavaScript. Pour une décision qui compte (création de compte, commande), validez aussi l'adresse depuis votre backend avec une clé serveur.

SMTP et crédits

C'est la clé rattachée au widget qui décide si le SMTP est exécuté, comme pour tout appel par clé. Chaque validation SMTP conclusive faite par le widget consomme un crédit. Pour borner la dépense :

• posez un plafond de crédits journalier sur la clé du widget ;
• gardez la limite SMTP par jour de la protection anti-abus (200 par défaut) ;
• laissez le déclenchement « à la sortie du champ » plutôt que « pendant la frappe ».

Sécurité, en bref

Protection	Rôle
Aucun secret dans la page	Le snippet ne contient que l'identifiant public du widget
Domaines autorisés	Le widget refuse de répondre depuis un site non déclaré (403)
Captcha Altcha	Preuve de travail calculée par le navigateur, vérifiée par le serveur
Limites par IP et appareil	Au-delà : validation dégradée sans SMTP, ou refus 429 avec Retry-After
Liste de blocage	Adresses IP bannies depuis le tableau de bord (403)
Détection d'énumération	Signal DUPLICATED_SUBMITTER quand une même source soumet beaucoup d'adresses différentes

Politique de sécurité du contenu (CSP)

Si votre site applique une CSP, autorisez le domaine de l'API pour le script et pour les appels :

Content-Security-Policy: script-src 'self' https://api.yeswecheck.fr; connect-src 'self' https://api.yeswecheck.fr; style-src 'self' 'unsafe-inline'

Le widget injecte une petite feuille de style dans la page, d'où style-src 'unsafe-inline'. Le captcha utilise l'API Web Crypto du navigateur, disponible seulement en HTTPS.

Dépannage

Symptôme	Cause probable
Rien ne se passe	Le script n'est pas chargé (CSP, bloqueur), ou aucun champ ne correspond au sélecteur. Voir la console : les messages commencent par [YesWeCheck Widget].
403 dans l’onglet réseau	Le domaine de la page n’est pas déclaré sur la clé du widget, ou l’IP est sur la liste de blocage.
404 widget not found	Identifiant erroné, widget supprimé ou désactivé.
429	Limite anti-abus atteinte pour cette IP ou cet appareil.
Le captcha échoue	Page servie en HTTP : la preuve de travail exige HTTPS.