Documentatie · Technische documentatie

Technische opmerkingen over Search Alerts

Dit document beschrijft de Search Agent / Smart Stock Alerts-functie: hoe bezoekers zich abonneren op opgeslagen zoekopdrachten, hoe de double-opt-in-procedure werkt, waar abonnementen worden opgeslagen en hoe de matching-engine na elke import wordt geactiveerd.

Wanneer dit document te gebruiken

Lees dit document als u het volgende moet doen:

  • Diagnose stellen bij ontbrekende of dubbele bevestigingsmails voor abonnementen.
  • Begrijpen hoe matching wordt uitgevoerd en welke criteria worden ondersteund.
  • Een database-back-up of migratie plannen die de abonnementstabel bevat.
  • Privacy- en gegevensretentiegedrag rond opgeslagen zoekopdrachten controleren.

Overzicht

De functie is geïmplementeerd in AS24CI\Search_Agent en:

  1. Rendert een abonnementsformulier (meestal binnen de zoekfilterzone) dat een POST-verzoek stuurt naar de AJAX-actie as24ci_search_agent_subscribe.
  2. Valideert het e-mailadres en de geselecteerde criteria, genereert een bevestigingstoken van 64 tekens en slaat een rij met de status pending (in afwachting) op.
  3. Verstuurt een bevestigingsmail met een link waarmee met één klik kan worden bevestigd via de token. Klikken op de link activeert het abonnement.
  4. Evalueert bij elke succesvolle voertuigimport elk actief abonnement tegen het nieuwe voertuig en verstuurt een meldingsmail wanneer de criteria overeenkomen.
  5. Biedt afmeldlinks in elke meldingsmail waarmee met één klik kan worden afgemeld.

Een bot-honeypot-veld (as24ci_hp_field) negeert geruisloos duidelijke bot-inzendingen terwijl het een succesrespons retourneert, zodat bots geen diagnostische informatie krijgen.

Database-tabel

Abonnementen worden opgeslagen in <prefix>as24ci_search_agents:

KolomTypeOpmerkingen
idBIGINT UNSIGNED AUTO_INCREMENTPrimaire sleutel.
nameVARCHAR(255) DEFAULT ''Optionele contactnaam.
emailVARCHAR(255) NOT NULLGevalideerd via is_email().
criteriaTEXTJSON-gecodeerde opgeschoonde criteria.
tokenVARCHAR(64) NOT NULL32-byte random_bytes() hex.
frequencyVARCHAR(20) DEFAULT 'daily'Tijdelijke aanduiding voor meldingsfrequentie.
statusVARCHAR(20) DEFAULT 'pending'pending, active, inactive, paused.
created_atDATETIME DEFAULT CURRENT_TIMESTAMPTijdstip van abonneren.
confirmed_atDATETIME NULLIngesteld wanneer de bezoeker op de bevestigingslink klikt.

Indexen: (status), (token). De schemaversie is opgeslagen in de optie as24ci_search_agent_db_version en dbDelta() wordt indien nodig toegepast.

Ondersteunde criteria

Search_Agent::sanitize_criteria() accepteert alleen deze whitelist van sleutels; alle andere velden die met het formulier worden verzonden, worden genegeerd:

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

Lege waarden en de letterlijke string all worden behandeld als "geen beperking" en verwijderd uit de opgeslagen criteria, zodat de matcher niet overmatig filtert.

Er moet na het opschonen ten minste één criterium overblijven; anders reageert het AJAX-eindpunt met HTTP 422 en een foutmelding.

Stap voor stap: abonnementsstroom

  1. De bezoeker selecteert criteria in het zoekfilter en verzendt zijn e-mailadres via het formulier van de search-agent.
  2. De frontend voert een POST-verzoek uit naar as24ci_search_agent_subscribe met de as24ci_search_agent nonce. Mislukte nonces retourneren HTTP 403.
  3. De plugin valideert het e-mailadres en de criteria, genereert een token, voegt een rij met de status pending toe en verstuurt de bevestigingsmail.
  4. De bezoeker klikt op de link (?as24ci_sa_action=confirm&token=<token>). De handler init controleert de lengte van de token (moet exact 64 tekens zijn), werkt de rij bij naar active en stelt confirmed_at in.
  5. Bij een succesvolle bevestiging wordt de bezoeker doorgestuurd naar de home-URL met ?as24ci_sa_msg=confirmed. De afmeldingsstroom gebruikt hetzelfde doorstuurmechanisme met unsubscribed.

Stap voor stap: matching-stroom

  1. De importer activeert as24ci_vehicle_imported na elke aanmaak of update.
  2. Search_Agent::on_vehicle_imported() wordt uitgevoerd met prioriteit 20.
  3. Updates worden overgeslagen — alleen voertuigen die nieuw zijn aangemaakt activeren meldingen, om te voorkomen dat abonnees worden gespamd wanneer een bestaand voertuig wordt gewijzigd.
  4. Actieve abonnementen worden geladen en hun criteria worden geëvalueerd tegen de taxonomieën (terms) en post-meta van het voertuig.
  5. Elke match resulteert in één meldingsmail die via wp_mail() wordt verzonden met de voertuigtitel, link, samenvatting van de criteria en de afmeld-URL.

Configuratiereferentie

De Search Agent-functie zelf wordt in- of uitgeschakeld via de plugin-functieschakelaar as24ci_feature_search_agent. E-mailsjablonen gebruiken platte tekst en zijn vertaalbaar. Het tokenformaat ligt vast (64 hex-tekens uit random_bytes(32)).

Voor de volledige lijst met plugin-opties, zie Options And Settings Storage.

Operationele opmerkingen

  • Het eindpunt is openbaar (wp_ajax_nopriv_* is geregistreerd) zodat anonieme bezoekers zich kunnen abonneren. Beveiliging is gebaseerd op de AJAX-nonce en de honeypot.
  • Tokens zijn cryptografisch willekeurig en worden opgeslagen als platte hexadecimale waarden. Behandel de tabel alsof deze persoonlijke gegevens bevat: naam, e-mailadres en de opgeslagen zoekcriteria van de bezoeker.
  • Updates activeren geen meldingen. Herimporten van bestaande advertenties (prijsverlaging, update van kilometerstand, enz.) zijn bewust stil. Controleer dit met de huidige plugin-versie als u van plan bent dit gedrag te wijzigen.
  • De kolom frequency is opgenomen in het schema voor toekomstig gebruik; de huidige matcher verzendt meldingen onmiddellijk bij elke nieuwe match.
  • De bevestigings- en afmeldeindpunten worden geleid via ?as24ci_sa_action=... queryparameters op de home-URL — er worden geen aangepaste herschrijfregels (rewrite rules) geïntroduceerd.
  • De tabel wordt verwijderd bij het deïnstalleren (onafhankelijk van de schakelaar gegevens verwijderen bij deïnstallatie) omdat deze persoonlijke gegevens bevat. Zie Uninstall And Cleanup Behavior.

Probleemoplossing

  • Geen bevestigingsmail ontvangen — controleer de spammappen; controleer vervolgens de SMTP-/mailerconfiguratie. De plugin gebruikt wp_mail() voor alle abonnementsberichten.
  • Bevestigingslink meldt niets — de token was leeg of niet exact 64 tekens, of de rij was al bevestigd. Het eindpunt stopt geruisloos als de token onjuist is geformatteerd; dit voorkomt enumeratie-aanvallen.
  • Abonnee ontvangt geen meldingen, zelfs niet na een overeenkomstige import — controleer of het voertuig nieuw is toegevoegd (updates sturen geen meldingen), of het abonnement op active staat, en of ten minste één criterium restrictief genoeg is om te koppelen aan een bekende meta-sleutel of taxonomie-term.
  • Veel dubbele meldingen tijdens een herimport — dit zou niet mogen gebeuren omdat updates worden uitgefilterd, maar een volledige herimport waarbij berichten vanaf nul opnieuw worden aangemaakt, zou wel meldingen activeren. Plan volledige herimporten tijdens rustige uren en overweeg om de Search Agent-schakelaar tijdelijk uit te schakelen.
  • AJAX-abonneren retourneert altijd succes, zelfs met ongeldige gegevens — het honeypot-veld is geactiveerd. Controleer of het formulier niet per ongeluk de verborgen invoer as24ci_hp_field heeft ingevuld.

Gerelateerde documenten