Notes techniques sur les alertes de recherche

Ce document décrit la fonctionnalité d'Agent de recherche / Alertes de stock intelligentes : comment les visiteurs s'abonnent aux recherches enregistrées, comment fonctionne le flux de double opt-in, où les abonnements sont stockés et comment le moteur de correspondance est déclenché après chaque importation.

Quand utiliser ce document

Lisez ce document si vous devez :

• Diagnostiquer des e-mails de confirmation d'abonnement manquants ou dupliqués.
• Comprendre comment la correspondance est effectuée et quels critères sont pris en charge.
• Planifier une sauvegarde ou une migration de base de données incluant la table des abonnements.
• Auditer le comportement en matière de confidentialité et de conservation des données concernant les recherches enregistrées.

Aperçu

La fonctionnalité est implémentée dans AS24CI\Search_Agent et :

1. Affiche un formulaire d'abonnement (généralement à l'intérieur de la zone de filtre de recherche) qui envoie une requête POST à l'action AJAX as24ci_search_agent_subscribe.
2. Valide l'e-mail et les critères sélectionnés, génère un jeton de confirmation de 64 caractères et stocke une ligne en attente (pending).
3. Envoie un e-mail de confirmation contenant un lien en un clic avec le jeton. Cliquer sur le lien active l'abonnement.
4. À chaque importation réussie de véhicule, évalue chaque abonnement actif par rapport au nouveau véhicule et envoie un e-mail de notification lorsque les critères correspondent.
5. Fournit des liens de désinscription en un clic dans chaque e-mail de notification.

Un champ piège à robots (honeypot) (as24ci_hp_field) rejette silencieusement les soumissions évidentes de robots tout en renvoyant une réponse de succès afin que les robots ne reçoivent pas d'informations de diagnostic.

Table de base de données

Les abonnements sont stockés dans <prefix>as24ci_search_agents :

Index : (status), (token). La version du schéma est stockée dans l'option as24ci_search_agent_db_version et dbDelta() est appliqué si nécessaire.

Critères pris en charge

Search_Agent::sanitize_criteria() n'accepte que cette liste blanche de clés ; tous les autres champs soumis avec le formulaire sont ignorés :

• make
• model
• body_type
• drive_type
• condition
• color
• min_price
• max_price
• mileage_max
• status

Les valeurs vides et la chaîne littérale all sont traitées comme "sans contrainte" et supprimées des critères stockés afin que le moteur de correspondance ne filtre pas de manière excessive.

Au moins un critère doit rester après le nettoyage ; sinon, le point de terminaison AJAX répond avec HTTP 422 et un message d'erreur.

Étape par étape : flux d'abonnement

1. Le visiteur sélectionne des critères dans le filtre de recherche et soumet son e-mail au formulaire de l'agent de recherche.
2. Le front-end envoie une requête POST as24ci_search_agent_subscribe avec le jeton de sécurité (nonce) as24ci_search_agent. Les jetons de sécurité échoués renvoient HTTP 403.
3. Le plugin valide l'e-mail et les critères, génère un jeton, insère une ligne en attente (pending) et envoie l'e-mail de confirmation.
4. Le visiteur clique sur le lien (?as24ci_sa_action=confirm&token=<token>). Le gestionnaire init vérifie la longueur du jeton (doit être de 64 caractères), met à jour la ligne en actif (active) et définit confirmed_at.
5. Lors d'une confirmation réussie, le visiteur est redirigé vers l'URL d'accueil avec ?as24ci_sa_msg=confirmed. Le flux de désinscription utilise le même mécanisme de redirection avec unsubscribed.

Étape par étape : flux de correspondance

1. L'importateur déclenche as24ci_vehicle_imported après chaque création ou mise à jour.
2. Search_Agent::on_vehicle_imported() s'exécute à la priorité 20.
3. Les mises à jour sont ignorées — seuls les véhicules nouvellement créés déclenchent des notifications, afin d'éviter de spammer les abonnés lorsqu'un véhicule existant est modifié.
4. Les abonnements actifs sont chargés et leurs critères sont évalués par rapport aux termes et aux métadonnées (post meta) du véhicule.
5. Chaque correspondance donne lieu à un e-mail de notification envoyé via wp_mail() contenant le titre du véhicule, le lien, le résumé des critères et l'URL de désinscription.

Référence de configuration

La fonctionnalité d'Agent de recherche elle-même est activée ou désactivée via le commutateur de fonctionnalité du plugin as24ci_feature_search_agent. Les modèles d'e-mails utilisent du texte brut et sont traduisibles. Le format du jeton est fixe (64 caractères hexadécimaux issus de random_bytes(32)).

Pour la liste complète des options du plugin, voir Options And Settings Storage.

Notes opérationnelles

• Le point de terminaison est public (wp_ajax_nopriv_* est enregistré) afin que les visiteurs anonymes puissent s'abonner. L'authentification repose sur le jeton de sécurité (nonce) AJAX et le piège à robots (honeypot).
• Les jetons sont générés de manière cryptographique aléatoire et stockés sous forme de texte hexadécimal brut. Traitez la table comme contenant des données personnelles : nom, e-mail et critères de recherche enregistrés du visiteur.
• Les mises à jour ne déclenchent pas de notifications. Les réimportations d'annonces existantes (baisse de prix, mise à jour du kilométrage, etc.) sont intentionnellement silencieuses. Vérifiez par rapport à la version actuelle du plugin si vous prévoyez de modifier ce comportement.
• La colonne frequency est incluse dans le schéma pour une utilisation future ; le moteur de correspondance actuel envoie les notifications immédiatement lors de chaque nouvelle correspondance.
• Les points de terminaison de confirmation et de désinscription sont acheminés via les paramètres de requête ?as24ci_sa_action=... sur l'URL d'accueil — aucune règle de réécriture personnalisée n'est introduite.
• La table est supprimée lors de la désinstallation (indépendamment du commutateur supprimer les données lors de la désinstallation) car elle contient des données personnelles. Voir Uninstall And Cleanup Behavior.

Dépannage

• Aucun e-mail de confirmation reçu — vérifiez les dossiers de courrier indésirable ; puis vérifiez la configuration SMTP/expéditeur d'e-mails. Le plugin utilise wp_mail() pour tous les messages d'abonnement.
• Le lien de confirmation ne signale rien — le jeton était vide ou ne faisait pas exactement 64 caractères, ou la ligne était déjà confirmée. Le point de terminaison s'arrête silencieusement si le jeton est mal formé ; cela empêche les attaques par énumération.
• L'abonné ne reçoit aucune notification même après une importation correspondante — confirmez que le véhicule était une nouvelle insertion (les mises à jour ne notifient pas), que l'abonnement est active, et qu'au moins un critère est assez restrictif pour correspondre à une clé de métadonnée ou à un terme de taxonomie connu.
• De nombreuses notifications en double lors d'une réimportation — cela ne devrait pas se produire car les mises à jour sont filtrées, mais une réimportation complète qui recrée les publications à partir de zéro déclencherait des notifications. Planifiez les réimportations complètes pendant les heures creuses et envisagez de désactiver temporairement le commutateur de l'Agent de recherche.
• L'abonnement AJAX renvoie toujours un succès même avec des données incorrectes — le champ piège à robots (honeypot) a été déclenché. Confirmez que le formulaire n'a pas rempli par inadvertance l'entrée masquée as24ci_hp_field.

Documents connexes

• AJAX Actions
• Cron Events And Scheduler
• Options And Settings Storage
• Security And Capabilities
• Uninstall And Cleanup Behavior
• Import Engine