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 lesen sollten

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

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

Übersicht

Die Funktion ist in AS24CI\Search_Agent implementiert und:

1. Rendert ein Abonnement-Formular (normalerweise innerhalb des Suchfilterbereichs), 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-stelliges Bestätigungs-Token und speichert eine Zeile mit dem Status ausstehend (pending).
3. Sendet eine Bestätigungs-E-Mail mit einem One-Click-Link, der das Token enthält. Durch Klicken auf den Link wird das Abonnement aktiviert.
4. Evaluiert bei jedem erfolgreichen Fahrzeugimport jedes aktive Abonnement im Vergleich zum neuen Fahrzeug und sendet eine Benachrichtigungs-E-Mail, wenn die Kriterien übereinstimmen.
5. Stellt in jeder Benachrichtigungs-E-Mail Links zum Abbestellen mit einem Klick bereit.

Ein Bot-Honeypot-Feld (as24ci_hp_field) verwirft offensichtliche Bot-Einsendungen geräuschlos, 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 wird 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 der Matcher nicht überfiltert.

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. Ungültige 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 ausstehend 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 aktiv und setzt confirmed_at.
5. Bei erfolgreicher Bestätigung wird der Besucher mit ?as24ci_sa_msg=confirmed zur Start-URL 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 (Terms) und Post-Meta-Daten 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.

Konfigurationsreferenz

Die Suchauftrags-Funktion selbst wird über den Plugin-Funktionsschalter as24ci_feature_search_agent aktiviert oder deaktiviert. E-Mail-Vorlagen verwenden reinen Text 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.
• Token sind kryptografisch zufällig und werden als reines Hex 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 Angebote (Preissenkung, Aktualisierung des Kilometerstands usw.) bleiben absichtlich stumm. Überprüfen Sie dies anhand der aktuellen Plugin-Version, wenn Sie planen, dieses Verhalten zu ändern.
• Die Spalte frequency ist im Schema für zukünftige Verwendungen enthalten; der aktuelle Matcher sendet Benachrichtigungen sofort bei jeder neuen Übereinstimmung.
• Die Bestätigungs- und Abmelde-Endpunkte werden über ?as24ci_sa_action=...-Abfrageparameter auf der Start-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 – Spam-Ordner prüfen; danach die SMTP-/Mailer-Konfiguration verifizieren. 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 geräuschlos 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-Schlüssel / Taxonomie-Term zugeordnet zu werden.
• Viele doppelte Benachrichtigungen während eines Re-Imports – sollte nicht vorkommen, da Aktualisierungen herausgefiltert werden. Ein vollständiger Re-Import, der Beiträge von Grund auf neu erstellt, würde jedoch Benachrichtigungen auslösen. Planen Sie vollständige Re-Importe in verkehrsarmen Zeiten und erwägen Sie, 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