Technische Hinweise zu Suchaufträgen

Dieses Dokument beschreibt die Funktion Suchauftrag / Smart Stock Alerts: wie Besucher gespeicherte Suchen abonnieren, wie der Double-Opt-In-Ablauf funktioniert, wo Abonnements gespeichert werden und wie die Matching-Engine nach jedem Import ausgelöst wird.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Fehlende oder doppelte Bestätigungs-E-Mails für Abonnements diagnostizieren.
• Verstehen, wie der Abgleich durchgeführt wird und welche Kriterien unterstützt werden.
• Ein Datenbank-Backup oder eine Migration planen, die die Abonnement-Tabelle enthält.
• Datenschutz und Datenaufbewahrungsverhalten rund um gespeicherte Suchen überprüfen.

Übersicht

Die Funktion ist in AS24CI\Search_Agent implementiert und:

1. Rendert ein Abonnement-Formular (normalerweise innerhalb des Suchfilter-Bereichs), das per POST an die AJAX-Aktion as24ci_search_agent_subscribe sendet.
2. Validiert die E-Mail und die ausgewählten Kriterien, generiert ein 64-Zeichen-Bestätigungs-Token und speichert eine Zeile mit dem Status pending (ausstehend).
3. Sendet eine Bestätigungs-E-Mail mit einem One-Click-Link, der das Token enthält. Das Klicken auf den Link aktiviert das Abonnement.
4. Gleicht bei jedem erfolgreichen Fahrzeugimport jedes aktive Abonnement mit dem neuen Fahrzeug ab und sendet eine Benachrichtigungs-E-Mail, wenn die Kriterien übereinstimmen.
5. Stellt in jeder Benachrichtigungs-E-Mail One-Click-Abmeldelinks bereit.

Ein Bot-Honeypot-Feld (as24ci_hp_field) verwirft offensichtliche Bot-Einsendungen stillschweigend, während es eine Erfolgsantwort zurückgibt, damit Bots keine Diagnoseinformationen erhalten.

Datenbank-Tabelle

Abonnements werden in <prefix>as24ci_search_agents gespeichert:

Indizes: (status), (token). Die Schema-Version ist in der Option as24ci_search_agent_db_version gespeichert und dbDelta() wird bei Bedarf angewendet.

Unterstützte Kriterien

Search_Agent::sanitize_criteria() akzeptiert nur diese Whitelist von Schlüsseln; alle anderen mit dem Formular übermittelten Felder werden verworfen:

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

Leere Werte und die literale Zeichenkette all werden als "keine Einschränkung" behandelt und aus den gespeicherten Kriterien entfernt, damit die Matching-Engine nicht zu stark filtert.

Mindestens ein Kriterium muss nach der Bereinigung übrig bleiben; andernfalls antwortet der AJAX-Endpunkt mit HTTP 422 und einer Fehlermeldung.

Schritt für Schritt: Abonnement-Ablauf

1. Der Besucher wählt Kriterien im Suchfilter aus und sendet seine E-Mail über das Suchauftrags-Formular ab.
2. Das Frontend sendet einen POST-Request an as24ci_search_agent_subscribe mit dem Nonce as24ci_search_agent. Fehlgeschlagene Nonces geben HTTP 403 zurück.
3. Das Plugin validiert die E-Mail und die Kriterien, generiert ein Token, fügt eine Zeile mit dem Status pending ein und sendet die Bestätigungs-E-Mail.
4. Der Besucher klickt auf den Link (?as24ci_sa_action=confirm&token=<token>). Der Handler init überprüft die Token-Länge (muss genau 64 Zeichen lang sein), aktualisiert die Zeile auf active und setzt confirmed_at.
5. Bei erfolgreicher Bestätigung wird der Besucher mit ?as24ci_sa_msg=confirmed auf die Startseite weitergeleitet. Der Abmelde-Ablauf verwendet denselben Weiterleitungsmechanismus mit unsubscribed.

Schritt für Schritt: Matching-Ablauf

1. Der Importer löst nach jedem Erstellen oder Aktualisieren as24ci_vehicle_imported aus.
2. Search_Agent::on_vehicle_imported() läuft mit der Priorität 20.
3. Aktualisierungen werden übersprungen – nur neu erstellte Fahrzeuge lösen Benachrichtigungen aus, um zu verhindern, dass Abonnenten mit Spam überhäuft werden, wenn sich ein bestehendes Fahrzeug ändert.
4. Aktive Abonnements werden geladen und ihre Kriterien werden mit den Taxonomien und dem Post-Meta des Fahrzeugs abgeglichen.
5. Jede Übereinstimmung führt zu einer Benachrichtigungs-E-Mail, die über wp_mail() gesendet wird und den Fahrzeugtitel, den Link, eine Zusammenfassung der Kriterien sowie die Abmelde-URL enthält.

Konfigurations-Referenz

Die Suchauftrags-Funktion selbst wird über den Plugin-Funktionsschalter as24ci_feature_search_agent aktiviert oder deaktiviert. E-Mail-Vorlagen verwenden Klartext und sind übersetzbar. Das Token-Format ist fest vorgegeben (64 Hex-Zeichen aus random_bytes(32)).

Die vollständige Liste der Plugin-Optionen finden Sie unter Speicherung von Optionen und Einstellungen.

Betriebliche Hinweise

• Der Endpunkt ist öffentlich (wp_ajax_nopriv_* ist registriert), sodass sich auch anonyme Besucher anmelden können. Die Authentifizierung basiert auf dem AJAX-Nonce und dem Honeypot.
• Tokens sind kryptografisch zufällig und werden als reiner Hex-Wert gespeichert. Behandeln Sie die Tabelle so, als ob sie personenbezogene Daten enthält: Name, E-Mail und die gespeicherten Suchkriterien des Besuchers.
• Aktualisierungen lösen keine Benachrichtigungen aus. Re-Importe bestehender Fahrzeuge (Preissenkung, Kilometeraktualisierung usw.) bleiben absichtlich stumm. Überprüfen Sie dies anhand der aktuellen Plugin-Version, falls Sie dieses Verhalten ändern möchten.
• Die Spalte frequency ist im Schema für eine zukünftige Verwendung enthalten; die aktuelle Matching-Engine sendet Benachrichtigungen sofort bei jeder neuen Übereinstimmung.
• Die Bestätigungs- und Abmelde-Endpunkte werden über ?as24ci_sa_action=...-Query-Parameter auf der Startseiten-URL geroutet – es werden keine benutzerdefinierten Rewrite-Rules eingeführt.
• Die Tabelle wird bei der Deinstallation gelöscht (unabhängig vom Schalter Daten bei Deinstallation löschen), da sie personenbezogene Daten enthält. Siehe Verhalten bei Deinstallation und Bereinigung.

Fehlerbehebung

• Keine Bestätigungs-E-Mail erhalten – Überprüfen Sie den Spam-Ordner und verifizieren Sie anschliessend die SMTP-/Mailer-Konfiguration. Das Plugin verwendet wp_mail() für alle Abonnement-Nachrichten.
• Bestätigungslink meldet nichts – Das Token war leer, entsprach nicht genau 64 Zeichen oder die Zeile wurde bereits bestätigt. Der Endpunkt bricht stillschweigend ab, wenn das Token fehlerhaft ist; dies verhindert Enumeration-Angriffe.
• Abonnent erhält auch nach einem passenden Import keine Benachrichtigungen – Stellen Sie sicher, dass das Fahrzeug neu angelegt wurde (Aktualisierungen benachrichtigen nicht), das Abonnement auf active steht und mindestens ein Kriterium restriktiv genug ist, um einem bekannten Meta-Key oder Taxonomie-Begriff zugeordnet zu werden.
• Viele doppelte Benachrichtigungen während eines Re-Imports – Dies sollte nicht vorkommen, da Aktualisierungen herausgefiltert werden. Ein vollständiger Re-Import, bei dem Beiträge von Grund auf neu erstellt werden, würde jedoch Benachrichtigungen auslösen. Planen Sie vollständige Re-Importe in verkehrsarmen Zeiten und ziehen Sie in Erwägung, den Suchauftrags-Schalter vorübergehend zu deaktivieren.
• AJAX-Abonnement gibt auch bei fehlerhaften Daten immer Erfolg zurück – Das Honeypot-Feld wurde ausgelöst. Stellen Sie sicher, dass das Formular nicht versehentlich das versteckte Feld as24ci_hp_field ausgefüllt hat.

Verwandte Dokumente

• AJAX-Aktionen
• Cron-Events und Scheduler
• Speicherung von Optionen und Einstellungen
• Sicherheit und Berechtigungen
• Verhalten bei Deinstallation und Bereinigung
• Import-Engine