Websource Newsletter pour WordPress — référence développeur

Vue d'ensemble

• Espace de noms Websource\Newsletter, classes dans src/ (chargeur PSR-4 maison, pas de Composer).
• Capacité requise pour l'administration et les routes REST protégées : manage_options (filtre websource_newsletter_capability).
• Fonctionne sans WooCommerce ; seul le code promo de bienvenue en dépend (VoucherService::available()).
• CSS (wsx-newsletter) et JavaScript (wsx-newsletter, différé, sans jQuery) chargés seulement quand un formulaire est rendu.

Données

Aucune adresse IP n'est enregistrée en clair. Le jeton de confirmation n'est conservé que sous forme d'empreinte et est effacé à la confirmation.

Réglages

Un texte vide prend la valeur par défaut traduite. {shop} est remplacé par le nom du site.

Bloc Gutenberg websource/newsletter

Rendu serveur (block.json, apiVersion 3, éditeur sans build). Catégorie Widgets. Alignements large et pleine largeur.

<!-- wp:websource/newsletter {"layout":"inline","showIntro":false} /-->

Code court [websource_newsletter]

[websource_newsletter layout="inline" intro="0"]

Fonctions publiques

// Renvoie le HTML du formulaire. Options : layout (card|inline), intro (bool), class, source.
echo websource_newsletter_form(['layout' => 'inline']);

// Inscrit une adresse pour un visiteur qui a donné un consentement explicite (formulaire maison).
// Renvoie 'accepted', 'invalid' ou 'consent'. La double confirmation s'applique si elle est activée.
$result = websource_newsletter_subscribe('prenom.nom@example.test', true, 'api');

websource_newsletter_subscribe() enregistre le texte de consentement courant du site : ne l'appelez que si ce texte a réellement été présenté et accepté.

Emplacements automatiques

Un thème peut placer lui-même le formulaire en déclenchant do_action('websource_before_footer') ou do_action('websource_footer'). Chaque emplacement n'est rendu qu'une fois par page.

Gabarits surchargeables

Copiez un gabarit de templates/ dans <thème>/websource-newsletter/ : form.php, fields.php, popup.php, result.php. Les variables sont dans $wsnl (ou $wsnl_result pour result.php).

Pages publiques

Ces pages envoient X-Robots-Tag: noindex, nofollow, Referrer-Policy: no-referrer et les en-têtes anti-cache.

Routes REST

Espace de noms websource-newsletter/v1.

POST /subscribe

Publique par conception (formulaire ouvert à tous les visiteurs), protégée par le champ piège, le tampon signé, le délai minimal et la limitation de débit.

curl -X POST https://example.test/wp-json/websource-newsletter/v1/subscribe \
  -H 'Content-Type: application/json' \
  -d '{"email":"prenom.nom@example.test","consent":true,"stamp":"1791572911.fc19…","website":"","source":"site"}'

{"success":true,"message":"Merci ! Un e-mail vient de vous être envoyé : cliquez sur le lien pour confirmer votre inscription.","field":""}

La réponse est toujours en HTTP 200 avec Cache-Control: no-store. En cas d'erreur, success vaut false et field vaut email, consent ou une chaîne vide. La réponse est identique que l'adresse soit déjà connue ou non.

GET /stats

Capacité requise. Sans authentification : 401.

{"status":{"pending":2,"confirmed":3,"unsubscribed":1},"vouchers":0,"total":6}

GET /subscribers

Capacité requise.

curl -H 'X-WP-Nonce: <nonce>' --cookie '<cookies de session>' \
  'https://example.test/wp-json/websource-newsletter/v1/subscribers?status=confirmed&per_page=1'

[{"id":7,"user_id":0,"email":"prenom.nom@example.test","status":"confirmed","source":"before_footer","locale":"fr_FR","date_mail":"2026-10-09 19:19:41","consent_date":"2026-10-09 19:19:41","consent_text":"J’accepte de recevoir la newsletter de …","consent_version":1,"consent_locale":"fr_FR","voucher_code":null,"date_add":"2026-10-09 19:19:41","date_upd":"2026-10-09 19:19:41","date_confirm":"2026-10-09 19:19:41","date_unsub":null}]

En-têtes X-WP-Total et X-WP-TotalPages. token_hash et token_expires ne sont jamais renvoyés.

DELETE /subscribers/<id>

Capacité requise. Efface l'abonné et sa preuve de consentement.

{"deleted":true}

Abonné inconnu : 404, code wsx_newsletter_not_found.

Filtres

// Derrière Cloudflare : limiter le débit sur l'adresse réelle du visiteur.
add_filter('websource_newsletter_client_ip', static function ($ip) {
    return isset($_SERVER['HTTP_CF_CONNECTING_IP']) ? sanitize_text_field(wp_unslash($_SERVER['HTTP_CF_CONNECTING_IP'])) : $ip;
});

Actions

// Envoyer chaque abonné confirmé à un outil d'envoi.
add_action('websource_newsletter_confirmed', static function (array $row): void {
    mon_outil_ajouter_contact($row['email'], $row['locale']);
});

Outils de confidentialité

• Exportateur websource-newsletter (wp_privacy_personal_data_exporters) : groupe « Abonnement à la newsletter » avec l'adresse, le statut, l'origine, la langue, la date, le texte et la version du consentement, les dates d'inscription, de confirmation et de désinscription, le code promo.
• Effaceur websource-newsletter (wp_privacy_personal_data_erasers) : supprime la ligne de l'abonné, remet la méta du compte à 0, supprime le code promo de bienvenue non utilisé (ou retire la restriction d'adresse d'un code déjà utilisé).
• Texte proposé dans Réglages > Confidentialité > Guide de politique.

Export CSV et JSON

CSV (séparateur ;, UTF-8 avec BOM, cellules commençant par =, +, -, @ neutralisées) :

email;status;source;lang;consent_date;consent_version;consent_text;date_add;date_confirm;date_unsub;voucher_code

JSON des réglages d'affichage (section newsletter, version 1). Une page est désignée par @type:slug, jamais par identifiant.

{
  "plugin": "websource-newsletter",
  "section": "newsletter",
  "version": 1,
  "data": {
    "placements": ["before_footer"],
    "custom_hook": "",
    "signup_field": true,
    "popup_enabled": false,
    "popup_mode": "delay",
    "popup_delay": 10,
    "popup_days": 7,
    "title": "",
    "intro": "",
    "consent": "",
    "policy_url": "privacy",
    "popup_title": "",
    "popup_intro": ""
  }
}

Jamais exportés ni importés : abonnés, clé secrète, version du consentement, code promo, anti-spam. Un texte de consentement différent à l'import augmente la version.

Variables CSS

Le formulaire lit les variables du thème avec une valeur de repli. Surchargez les variables --wsnl-* sur .wsnl.

Classes : .wsnl, .wsnl--card, .wsnl--inline, .wsnl--placed, .wsnl--at-before-footer, .wsnl--at-footer, .wsnl--at-home, .wsnl--at-custom, .wsnl--popup, .wsnl-popup (<dialog>). Le bandeau passe en deux colonnes quand le formulaire lui-même dépasse 52 rem (requête de conteneur).

Polylang et WPML

Les textes saisis (title, intro, consent, popup_title, popup_intro) sont déclarés par pll_register_string (groupe « Websource Newsletter ») et wpml-config.xml. L'e-mail est envoyé dans la langue enregistrée avec l'abonné quand elle est installée sur le site.

Désinstallation

uninstall.php supprime l'évènement planifié. Si keep_data est décoché, il supprime aussi les deux tables, les quatre options et les métas utilisateur wsx_newsletter_optin et wsx_newsletter_per_page.